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Acknovfledgemcnts and Background 

INTERLISP (formerly BBN LISP) has evolved from a succession of LISP systems 
that began with a LISP designed and implemented for the DEC POP-1 by D. G. 
Bobrovr and D. L. Nurphy' at Bolt, Beranek and Newman in 1966* and documented by 
D. G. Bobrow. An upwards compatible version of this LISP was implemented for 
the SDS 940 in 1967, by Bobrow and Murphy. This system contained the seeds for 
many of the capabilities and features of the current system: a compatible 
compiler and interpreter, uniform error handling, an on-line LISP oriented 
editor,^ sophisticated debugging facilities,^ etc. 940 LISP was also the first 
LISP system to demonstrate the feasibility of using software paging techniques 
and a large virtual memory in conjunction with a list-processing system CBob2]. 
DWIN, the Do-What-I-Nean error correction facility, was introduced into the 
system in 1968 by W. Teitelman CTeiZ], who was also responsible for 
documentation for the 940 LISP system. 



D. G. Bobrow is currently at Xerox Palo Alto Research Center (PARC), D. L. 
Murphy is with Digital Equipment Corp. 

The preliminary version of the compiler was written by L. P. Deutsch, now 
at Xerox PARC. This was considerably modified and extended by D. L. Murphy 
before producing the final working version. 

The original idea of a LISP oriented structure editor belongs to L. P. 
Deutsch. The editor in its current form was written by W. Teitelman, now 
of Xerox PARC. 

Designed and implemented by W. Teitelman. 
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In 1970, an upwards compatible version of 940 LISP called BBN LISP was 
designed for the PDP-10 by D. G. Bobrow, D. L. Murphy. A. K. Hartley, and W. 
Teitelman, and implemented by Hartley with assistance from Murphy. A, 
Hartley was also responsible for modifying the 940 LISP compiler to generate 
code for the PDP-10. BBN-LISP ran under TENEX. a sophisticated time sharing 
system for the PDP-IO designed and implemented by D. G. Bobrow, J. D. 
Burchfiel, D. L. Murphy, T. R. Strollo, and R. S. Tomlinson.CBobl] With 
hardware paging and 256IC of virtual memory provided by TENEX, it became 
practical to provide extensive and sophisticated interactive user support 
facilities, such as the programmer's assistant CTei4], CLISP [TeiS], and a more 
sophisticated DWIN, all of which were designed and developed by W. Teitelman. 
In 1971, the block compiler was designed and implemented by D. G. Bobrow. The 
BBN-LISP Manual [Tei33 was written by W. Teitelman, with contributions from A. 
K. Hartley and from J. W. Goodwin, who also wrote TRANSOR and the special 
arithmetic functions, as well as a number of other utility functions. The name 
of the system was changed from BBN-LISP to INTERLISP in 1973, when the 
maintenance and development of the system evolved into a joint effort between 
Bolt Beranek and Newman, and Xerox Palo Alto Research Center. The INTERLISP 
reference mahUal was written by W. Teitelman, with contributions from A. K. 
Hartley, J. W. Goodwin, and D. G. Bobrow. The cover was designed by 
Alice R. Fikes. 

INTERLISP is currently the LISP system used at Bolt Beranek and Newman, Xerox 
Palo Alto Research Center, Stanford Research Institute Artificial Intelligence 
Center, Information Sciences Institute, and the Dendral Project at Stanford 
University, in addition to being available at Computer Corporation of America 



The design, construction and documentation for BBN LISP was sponsored by 
the Information Processing Techniques Section of the Advanced Research 
Project Agency, as was all of the subsequent work on the system that was 
performed at BBN. Since March 1972, the contributions made to the 
development of the system by W. Teitelman, including the preparation of 
this manual, were sponsored by Xerox Palo Alto Research Center. 
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and Case Institute of Technology. The total user community now comprises 
approximately one hundred users. 

INTERLISP is a continuously evolving system, both in response to complaints, 
suggestions, and requests of the many users scattered throughout the ARPA 
network, as well as the long range goals of the individuals primarily 
responsible for the system, which are currently: 



Person 
W. Teitelman 
Xerox Palo Alto 

Research Center 
3180 Porter Dr. 
Palo Alto, Calif. 94304 



Responsible for 

User Facilities: i.e., pretty- 
print, editor, break and trace, 
advising, printstructure, DWIN, 
CLISP, programmer's assistant. 



A. K. Hartley 
Bolt Beranek & Newman 
50 Noulton St. 
Cambridge, Mass. 02138 



J. W. Goodwin 
Bolt Beranek & Newman 
50 Moulton St. 
Cambridge, Mass. 02138 



Basic System: i.e., interpreter, 
input-output, garbage collector; plus 
all SUBRS, i.e. hand-coded machine language 
functions such as PRINT, CONS, PROG, GO, 
etc.; plus compiler. 

Special Arithmetic Functions: e.g. 
LOG, SIN, SQRT, etc.; plus functions 
for accessing TENEX capabilities 
such as SUBSYS, FILDIR, et al.; 
plus TRANSOR as well as various 
utility functions such as LOADFNS, 
SORT, etc. (as indicated in the text 
of this manual). 



The preparation of this manual has involved the efforts of several persons at 
Xerox PARC, whom I specifically want to mention, and to express my appreciation 
for their support through this arduous, and at times seemingly endless task. 
Thank you Suzan (Jerome), Janet (Farness), Peter (Deutsch), Bob (Walker), and 
Larry (Tesler). I couldn't have done it without you. 



Warren Teitelman 
Palo Alto 
December, 1973. 
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SECTION 1 
INTRODUCTION 



This document is a reference manual for INTERLISP, a LISP system currently 
implemented on the DEC PDP-10 under the BBN TENEX time sharing system. CBobl] 
INTERLISP^ is designed to provide the user access to the large virtual memory 
allowed by TENEX» with a relatively small penalty in speed (using special 
paging techniques described in [Bob2]). Additional data types have been added, 
including strings, arrays, and hash association tables (hash links) (Sections 7 
and 10). The system includes a compatible compiler (Section 18) and 
interpreter. Machine code can be intermixed with INTERLISP expressions via the 
assemble directive of the compiler. The compiler also contains a facility for 
"block compilation" which allows a group of functions to be compiled as a unit, 
suppressing internal names. Each successive level of computation, from 
interpreted through compiled, to block-compiled provides greater speed at a 
cost of debugging ease. 

INTERLISP has been designed to be a good on-line interactive system. Some of 
the features provided include elaborate debugging facilities with tracing and 
conditional breakpoints (Section 15), and a sophisticated LISP oriented editor 
within the system (Section 9). Utilization of a uniform error processing 
through user accessible routines (Section 16) has allowed the implementation of 
DWIN, a Do-What-X-Nean facility, which automatically corrects many types of 
errors without losing the context of computation (Section 17). The CLISP 



INTERLISP (formerly BBN LISP) is the most recent incarnation in a 
succession of LISP systems. See Acknowledgements at front of manual. 
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facility (Section 23) extends the LISP syntax by enabling ALGOL-like infix 
operators such as +, «, /, «, AND, OR, etc., as well as IF-THEN-ELSE 
statements and FOR-WHILE-DO statements. CLISP expressions are automatically 
converted to equivalent LISP forms when they are first encountered. CLISP also 
includes list construction operators, as well as a LISP oriented pattern match 
compiler. 

A novel and useful facility of the INTERLISP system is the programmer's 
assistant (Section 22), which monitors and records all user inputs. The user 
can instruct the programmer's assistant to repeat a particular operation or 
sequence of operations, with poiisible modifications, or to UNDO the effects of 
specified operations. The goal of the programmer's assistant, DWIN, CLISP, 
etc. is to provide a programming environment which will "cooperate" with the 
user in the development of his programs, and free him to concentrate more fully 
on the conceptual difficulties and creative aspects of the problem he is trying 
to solve. 

To aid in converting to INTERLISP programs written in other LISP dialects, 
e.g., LISP 1.5, Stanford LISP, we have implemented TRANSOR, a subsystem which 
accepts transformations (or can operate from previously defined 
transformations), and applies these transformations to source programs written 
in another LISP dialect, producing object programs which will run on INTERLISP 
(Appendix 1). In addition, TRANSOR alerts the programmer to problem areas that 
(may) need further attention. TRANSOR was used extensively in converting from 
940 LISP to BBN-LISP on the PDP-10. A set of transformations is available for 
converting from Stanford LISP and LISP 1.5 to INTERLISP. 

A complete format directed list processing system FLIP [Teil], is available for 
use within INTERLISP. 

Although we have tried to be as clear and complete as possible, this document 
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is not designed to be an introduction to LISP. Therefore, sone parts may only 
be clear to people who have had some experience with other LISP systems. A 
good introduction to LISP has been written by Clark Weissroan [Weil]. Although 
not completely accurate with respect to INTERLISP, the differences are small 
enough to be mastered by use of this manual and on-line interaction. Another 
useful introduction is given by Berkeley [Berl] in the collection of Berkeley 
and Bobrow [BerZ]. « 

Changes to this manual will be issued by replacing sections or pages, and 
reissuing the index and table of contents at periodic intervals. In addition, 
the manual will be maintained on-line, and up to date versions of any or all 
chapters will be available in the form of TENEX files from W. Teitelman at 
Xerox PARC. 
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SECTION 2 
USING INTERLISP 



2.1 Using the I NTERL ISP Manual - Format . Notation, and Conventions 

The INTERLISP manual is divided into separate more or less independent 
sections. Each section ii paginated independently, to fatilitate issuing 
updates of sections. Each section contiains an index to key words, functions, 
and variables contained in that section. In addition, there is a composite 
index for the entire manual, plus several appendices and a table of contents. 

Throughout the manual, terminology and conventions will be offset from the text 
and typed in italics, frequently at the beginning of a section. For example, 
one such notational convention is: 

The names of Junctions and variables are mritten in loioer case and underlined 
when they appear in the text. Meta- LISP notation is used for describing forms. 

Examples: member[x;y] is equivalent to (MEMBER X Y), memberCcarCx];FOO] is 
equivalent to (MEMBER (CAR X) (QUOTE FOO)). Note that in meta-LISP notation 
lower case variables are evaluated, upper case quoted. 

. notation is used to distinguish between cons and list , 

e.g., if xa(A B C), (FOO x) is (FOO (A B C)), whereas (FOO . x) 

is (FOO ABC). In other words, x is cadr of (FOO x) but cdr of (FOO . x). 

Similarly, y is caddr of (FOO x y), but cddr of (FOO x . y). Note that this 
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convention is in fact followed by the read program, 
i.e., (FOO . (A B C)) and (FOO ABC) read in as equal structures. 

Other important conventions are: 

TRUE in IKTERUSP means not KIL, 

The purpose of this is to allow a single function to be used both for the 
computation of some quantity, and as a test for a condition. For example, the 
value of member[x;y] is either NIL, or the tail of ^ beginning with x. 
Similarly, the value of or is the value of its first TRUE, i.e., non-NIL, 
expression, and the value of and is either NIL, or the value of its last 
expression. 

Although most lists terminate in NIL, the occasional list that ends in an atom, 
e.g., (A B . C) or worse, a nucnber or string, could cause bizarre effects. 
Accordingly, we have made the following implementation decision: 

All functions that iterate through a list, e,g., member , length , mapc , etc. 
terminate by an nlis.tp check, rather than the conventional null'Check» as a 
safety precaution against encountering data types which might cause infinite 
cdr loops, e.g., strings, numbers, arrays. 

Thus, roember[x;(A B . C)]smember[xi(A B)] 
reversG[(A B . C)]sreverse[ (A B)] 
append[(A B . C) ;y]sappend[ (A B);y] 

For users with an application requiring extreme efficiency,^ we have provided 
fast versions of memb . last, nth, assoc . and length which compile open and 



A NIL check can be executed in only one instruction, an nlistp requires 
about 12, although both generate only one word of code. 
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terminate on NIL checks^ and therefore may cause infinite cdr loops if given 
poorly formed arguments. However, to help detect these situations, f memb , 
f last , fnth , fassoc , and f length all generate errors when interpreted if their 
argument ends in a non-list other than NIL, e.g. BAD ARGUNENT - FLAST. 



nost functions that set system parameters ^ e.g., printlevel , linelength , radix , 
etc., return as their value the old setting. If given ill L as an argument , they 
return the current value without changing it. 

All SUBBS, i.e., hand coded functions, such as read, print , eual , cons , etc., 
have 'argument names' (U U Vl) as described under arglist . Section 8. However, 
for tutorial purposes, more suggestive names are used in the descriptions of 
these functions in the text. 

Nost functions whose names end in £ are predicates* e,g. number p . tailp , exprp i 
most fufictions whose names end in g are nlambda*s, i.e., do not retfuire quoting 
their arguments , e.g., set(r , define<r , nlsetq . 

**x is equal to means equal[xtyj is true, as opposed to '*x is to y" 
meaning eqtxtyj is true, i.e., x and y are the same identical LISP pointer. 

When new literal atoms are created (by the read program, pack , or mkatom ) , they 
are provided with a function definition cell initialized to NIL (Section 8), a 
value cell initialized to the atom NOBIlilD (Section 16), and a property list 
initialized to NIL (Section 7). The function definition cell is accessed by 
the functions getd and putd described in Section 8. The value cell of an atom 
is car of the atom, and its property list is cdr of the atom. In particular, 
car of NIL and cdr of NIL are always NIL, and the system will resist attempts 
to change them. 

The term list refers to any structure created by one or more conses, i.e. it 
does not have to end in NIL. For example, (A . B) is a list . The function 
listp . Section 6, is used to test for lists. Note that not being a list does 
not necessarily imply an atom, e.g., strings and arrays are not lists, nor are 
they atoms. See Section 10. 

Nany system functions have extra optional arguments for internal use that are 
not described in the writeups. For example, readline is described as a 
function of no arguments, but arglist[fiEADLIN£J returns (LINE LISPXFLG). In 
such cases, the user should Just ignore the extra arguments. 



INTERLISP departs from LISP 1.5 and other LISP dialects in that cor of a form 
is never evaluated. In other words, if car of a form is not an atom with a 
function definition, and not a function object, i.e. a list car of which is 
LAMBDA, NLAN6DA, or FUNARG, an error is generated, apply or apply * (section 8) 
must be used if the name of a function is to be computed as for example, when 
functional arguments are applied. 
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2.2 Using the INTERLISP System on TENEX - An Overview 



Call INTERLISP by typing LISP followed by a carriage return. INTERLISP will 
type an identifying message, the date, and a greeting, followed by a '«-*. This 
prompt character indicates that the user is "talking to** the top level 
INTERLISP executive, called evalqt . (for historical reasons), just as '9' 
indicates the user is talking to TENEX. evalqt calls lispx which accepts 
inputs in either eval or apply format: if Just one expression is typed on a 
line, it is eval uated; if two expressions are typed, the first is apply ^ed to 
the second, eval and apply am described in section 8. In both cases, the 
value is typed, followed by indicating INTERLISP is ready for another input. 

INTERLISP is normally exited via the function LOGOUT, i.e., the user types 
LOGOUT(). However, typing control-C at any point in the computation returns 
control immediately to TENEX. The user can then continue his program with no 
ill effects with the TENEX CONTINUE command, even if he interrupted it during a 
garbage collection. Or he can reenter his program at evalqt with the TENEX 
REENTER command. The latte r is DEFIKITELY not advisable i£ the Control-C was 
typed during a garbage collection . Typing control-D at any point during a 
computation will return control to evalqt . If typed during a garbage 
collection, the garbage collection will first be completed, and then control 
will be returned to INTERLISP *s top level, otherwise, control returns 
immediately. 

When typing to the INTERLISP read program, typing a control-Q will cause 
INTERLISP to print '##' and clear the input buffer, i.e., erase the entire line 
up to the last carriage return. Typing control-A erases the last character 
typed in, echoing a \ and the erased character. Control-A will not back up 
beyond the last carriage return. Control-0 can be used to inmediatelu clear 
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the output buffer, and rubout to iimediiatelu clear the input buffer. In 
addition, typing control-U (in nost cases) will cause the INTERLISP editor 
(Section 9) to be called on the expression being read, when the read is 
completed. Appendix 3 contains a list of all control characters, and a 
reference to that part of the manual where they are described. 

Since the INTERLISP read program is normally line-buffered to make possible the 
action of control-Q,^ the user must type a carriage return before any 
characters are delivered to the function requesting input, e.g., 

T 

However, the read program automatically supplies (and prints) this carriage 
return when a matching right parenthesis is typed, making it unnecessary for 
the user to do so, e.g., 

^CONS(A B) 
(A . B) 

The INTERLISP read program treats square brackets as *super-parentheses' : a 
right square bracket automatically supplies enough right parentheses to match 
back to the last left square bracket (in the expression being read), or if none 
has appeared, to match the first left parentheses, 
e.g.. (A (B (C]«(A (B (C))), 

(A [B (C (03 E)-(A (B (C (D))) E). 



The action of control-Q takes place when it is read. If the user has 
'typed ahead' several inputs, control-Q will only affect at most the last 
line of input. Rubout however will clear the entire input buffer as soon 
as it is typed, i.e., even during a garbage collection. 



Except following control[T], see Section 14. 



*,>* is used throughout the manual to denote carriage-return. 
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% is the universal escape character for read . Thus to input an atom containing 
a syntactic delimiter, precede it by X, e.g. ABX (C or XX. See Section 14 for 
more details. 

Most of the "basics" of on-line use of INTERLISP, e.g. defining functions, 
error handling, editing, saving your work, etc., are illustrated in the 
following brief console session. Underlined characters were typed by the user. 

1. The user calls INTERLISP from TENEX, INTERLISP prints a date, and a 
greeting. The prompt character indicates the user is at the top level of 
INTERLISP. 

2. The user defines a function, fact , for computing factorial of n. In 
INTERLISP, functions are defined via DEFINE or OEFINEQ, (Sections). 
Functions may independently evaluate arguments, or not evaluate them, and 
spread their arguments, or not spread them (Section 4). The function fact 
shown here is an example of an everyday run-of"the-mlll function of one 
argument, which is evaluated. 

3. The user "looks" at the function definition. Function definitions in 
INTERLISP are stored in a special cell called the function definition cell, 
which is associated with the name of the function (Section 6). This cell 
is accessible via the two functions, getd and putd , (define and def Ineq use 
putd ) . Note that the user typed an input consisting of a single 
expression, i.e. (GETD (QUOTE FACT)), which was therefore interpreted as a 
form for eval . The user could also have typed GETO(FACT). 

4. The user runs his function. Two errors occur and corrections are offered 
by DWIN (Section 17). In each case, the user indicates his approval, DWIN 
makes the correction, i.e. actually changes the definition of fact , and 
then continues the computation. 
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@ LISP^ 



1 



INTERLISP-10 11-17-73 ... 

GOOD EVENING. 

^DEFINEQ((FACT (LAMBDDA (N) (COND ((EQ N 0) NIL) 2 
(T (ITIMES N (FACTT (SUBl Nl 

(FACT) 

^ (GETD (QUOTE FACT)) 3 
(LAMBDDA (N) (COND ((EQ N 0) NIL) (T (ITIMES N (FACTT (SUBl N)))))) 
»- FACT(3) 4 
LAMBDDA [IN FACT] -> LAMBDA ? YES^ 
FACTT [IN FACT] -> FACT ? YESi" 

NON-NUMERIC ARG 5 
NIL 

IN ITIMES 

(BROKEN) % 

:BT> 

ITIMES 

COND 

FACT 

COND 

FACT 

COND 

FACT 

**TOP** 



1 

; EDITF(FACT) 
EDIT 

* (R NIL 1) 

*0IO 

FACT 

: RETURN Q 
'BREAK' » 1 
6 

♦• PP FACT^ 

(FACT 

[LAMBDA (N) 
(COND 

((EQ N 0) 
1) 

(T (ITIMES N (FACT (SUBl N]) 

FACT 

♦• PRETTYDEF((FACT) FACT) 
FACT.;1 



7 

8 

9 
10 

11 
12 



13 
14 
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5. An error occurs that DWIN cannot handle, and the system goes into a break. 
At this point, the user can type in expressions to be eval-ed or apply-ed 
exactly as at the top level. The prompt character indicates that the 
user is in a break, i.e. that the context of his computation is available. 
In other words, the system is actually "within" or "below" the call to 
itimes in which the error occurred. 

6. The user types in the break command, BT, which calls for a backtrace to be 
printed. In INTERLI8P, interpreted and compiled code (see Section 18 for 
discussion of the compiler) are completely compatible, and in both cases, 
the name of the function that was called, as well as the names and values 
of its arguments are stored on the stack. The stack can be searched and/or 
modified in various ways (see Section 12). 



Break commands are discussed in Section 15, which also explains how the 
user can "break" a particular function, i.e. specify that the system go 
into a "break" whenever a certain function or functions are called. At 
that point the user can examine the state of the computation. This 
facility is very useful for debugging. 

7. The user asks for the value of the variable n, i.e. the most recent value, 
or binding. The interpreter will search the stack for the most recent 
binding, and failing to find one, will obtain the top level value from the 
atom's value cell, which is car of the atom (Section 3). If there are no 
bindings, and the value cell contains the atom NOBINO, an unbound atom 
error is generated (Section 16). 

8. The user realizes his error, and calls the editor to fix it. (Note that 
the system Is still in the break.) The editor is described at length and in 
detail in Section 9. It is an extremely useful facility of INTERLISP. 
Section 9 begins with a simple introduction designed for the new user. 
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9. The user instructs the editor to replace all NIL'S (in this case there is 
only one) by 1. The editor physically changes the expression it is 
operating on so when the user exits from the editor, his function, as it 
is now being interpreted, has been changed. 

10. The user exits from the editor and returns to the break. 

11. The user specifies the value to be used by itimes in place of NIL by using 
the break command RETURN. This causes the computation to continue, and 6 is 
ultimately returned as the value of the original input, fact(3). 

12. The user prettyprints (Section 14) fact , i.e. asks it be printed with 
appropriate indentations to indicate structure. Prettyprint also provides 
a comment facility. Note that both the changes made to fact by the editor 
and those made by DWIN are in evidence. 

13. The user writes his function on a file by using prettydef (Section 14), 
creating a TENEX file, FACT.;1, which when loaded into INTERLISP at a later 
date via the function load (Section 14), will cause fact to be defined as 
it currently is. There is also a facility in INTERLISP for saving and 
restoring an entire core image via the functions sysout and sysin 
(Section 14). 

14. The user logs out, returning control to TENEX. However, he can still 
continue his session by re-entering INTERLISP via the TENEX REENTER or 
CONTINUE command. 
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SECTION 3 

DATA TYPES, STORAGE ALLOCATION, AND GARBAGE COLLECTION^ 

INTERLISP operates in «n 18-bit address space. This address space is divided 
into 512 word pages with a liniit of 512 pages, or 26^,144 words, but only that 
portion of address space currehtly in use actually exists on any storage 
mediUBi. INTERLISP itself and all data storatie are contained within this 
address space. A pointer to a data eleneht such as a ituaber, atoa, etc., is 
simply the address of the data elenent in this 18-bit address space. 

3.1 Data Types 

The data types of INTERLISP are lists, atons, pnames, arrays, large and snail 
integers, floating point numbers, string characters .and string pointers. 
Compiled code and hash arrays are currently included with arrays. 

In the descriptions of the various data types given below, for each data type, 
first the input syntax and output format are described, that is, what input 
sequence will cause the INTERLISP read program to construct an element of that 
type, and how the INTERLISP print program will print such an element. Next, 
those functions that construct elements of that data type are given. Note that 
some data types cannot be input, they can only be constructed, e.g. arrays. 
Finally, the format in which an element of that data type is stored in memory 
is described. 



This section was written by A. K. Hartley. 
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3.1.1 Literal Atoms 



A literal atom is input as any string of non-delimiting characters that cannot 
be interpreted as a number. The syntatic characters that delimit atoms are 
space, end-of-line,^ line-feed, X ( ) " ] and [. However, these characters nay 
be included in atoms by preceding them with the escape character X. 

Literal atoms are printed by print and prinZ as a sequence of characters with 
X's inserted before all delimiting characters (so that the atom will read back 
in properly). Literal atoms are printed by prinl as a sequence of characters 
without these extra X's. For example, the atom consisting of the five 
characters A, B, C, (, and D will be printed as ABCX(D by print and ABC(0 by 
prinl . The extra X*s are an artifact of the print program; they are not stored 
in the atom's pname. 

Literal atoms can be constructed by pack , mkatom, and gensym (which uses 
mkatom ) . 

Literal atoms are unique. In other words, if two literal atoms have the same 
pname, i.e. print the same, they will always be the same identical atom, that 
is, they will always have the same address in memory, or equivalently, they 
will always be eg.^ Thus if pack or mkatom is given a list of characters 
corresponding to a literal atom that already exists, they return a pointer to 
that atom, and do not make a new atom. Similarly, if the read program is given 
as input of a sequence of characters for which an atom already exists, it 
returns a pointer to that atom. 



An end-of-line character is transmitted by TENEX when it sees a 
carriage-return. 

Note that this is not true for strings, large integers, floating point 
numbers, and lists, i.e. they all can print the same without being eg. 
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A literal atom is a 3 word (36 bits) datum containing: 



WORD l: 



WORD 2: 



WORD 3: 



PROPERTY LIST 
(CDR) 


TOP LEVEL BINDING 
(CAR) 


0 


17 


18 35 


FUNCTION CALLING INSTRUCTION 


0 




35 


PNAME 


RESERVED FOR FUNCTIONS 
ON FILES 


0 


17 


18 35 




FIGURE 3- 


-1 



Car of a literal atom, i.e. the right half of word 1, contains its top level 
binding, initially the atom NOBIND. Cdr of the atom is a pointer to its 
property list, initially NIL. 



Word 2, the function definition cell, is a full 36 bit word, containing an 
instruction to be executed for calling the function associated with that atom, 
if any. The left half differs for different function types (i.e., EXPR, SUBR, 
or compiled code); the right half is a pointer to the function definition.^ 

The pname cell, the left half of the third word, contains a pointer to the 
pnaroe of the atom. The remaining half word is reserved for an extension of 
INTERLISP to permit storing function definitions on files. 



This use of a full word saves some time in function calls from compiled 
code in that we do not need to look up the type of the function definition 
at call time. 
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3.1«2 Pnames 



The pnames of atons, pointed to in the third word of the atom, comprise 
another data type with storage assigned as it is needed. This data type only 
occurs as a component of an atom or a string. It does not appear, for example, 
as an element of a list. 

Pnames have no input syntax or output format as they cannot be directly 
referenced by user programs. 

A pname is a sequence of 7 bit characters packed 5 to a word, beginning at a 
word boundary. The first character of a pname contains its length; thus the 
maximum length of a pname is 126 characters. 

3.1.3 Numerical Atoms 

Numerical atoms, or simply numbers, do not have property lists, value cells, 
functions definition cells, or explicit pnames. There are currently two types 
of numbers in INTERLISP: integers, and floating point numbers. 



Integers 

The input syntax for an integer is an optional sign (♦ or -) followed by a 



All INTERLISP pointers have pnames, since we define a pname simply to be 
how that pointer is printed. However, only literal atoms and strings have 
their pnames explicitly stored. Thus, the use of the term pname in a 
discussion of data types or storage allocation means pnames of atoms or 
strings, and refers to a sequence of characters stored in a certain part of 
INTERLISP 's memory. 
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sequence of digits, followed by an optional Q. If the Q is present, the digits 
are interpreted in octal, otherwise in decinal, e.g. 77Q and 63 both correspond 
to the same integers, and in fact are indistinguishable internally since no 
record is kept of how integers were created. 

The setting of radix (Section 14), deternines how integers are printed: signed 
or unsigned, octal or decinal. 

Integers are created by pack and mkatom when given a sequence of characters 
observing the above syntax, e.g. (PACK (LIST 1 2 (QUOTE Q))) « 10. Integers 
are also created as a result of arithmetic operations, as described in Section 
13. 

An integer is stored in one 36 bit word; thus its magnitude must be less than 
2t35. To avoid having to store (and hence garbage collect) the values of small 
integers, a few pages of address space, overlapping the INTERLISP machine 
language code, are reserved for their representation. The small number pointer 
itself, minus a constant, is the value of the number. Currently the range of 
*small* integers is -1536 thru '••1535. The predicate smallp is used to test 
whether an integer is 'small*. 

Vfhile small integers have a unique representation, large integers do not. In 
other words, two large integers may have the same value, but not the same 
address in memory, and therefore not be eg. For this reason the function eqp 
(or equal ) should be used to test equality of large integers. 
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and terminated by a delimiting character. Note that some data types are 

self -delimiting, e.g. lists. 

If the sequence of digits used to create the integer is too large, the high 
order portion is discarded. (The handling of overflow as a result of 
arithmetic operations is discussed in Section 13.) 
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Floating Point Numbers 



A floating point number is input as a signed integer, followed by a decimal 
point, followed by another sequence of digits called the fraction, followed by 
an exponent (represented by E followed by a signed Integer). Both signs are 
optional, and either the fraction following the decimal point, or the integer 
preceding the decimal point may be omitted. One or the other of the decimal 
point or exponent may also be omitted, but at least one of them must be present 
to distinguish a floating point number from an integer. For example, the 
following will be recognized as floating point numbers: 

5. 5.00 5.01 .3 5E2 5.1E2 

5E-3 -5.2E46 

Floating point numbers are printed using the facilities provided by TENEX. 
INTERLISP calls the floating point number to string conversion routines^ using 
the format control specified by the function fltfmt (Section 14). fltfmt is 
initialized to T, or free format. For example, the above floating point 
numbers would be printed free format as: 

5.0 5.0 5.01 .3 500.0 510.0 

.005 -5.2E6 

Floating point numbers are also created by pack and rokatoro , and as a result of 
arithmetic operations as described in section 13. 

A floating point number is stored in one 36 bit word in standard PDP-10 format. 
The range is j:2.94E-39 thru j:1.69'E38 (or 2t-128 thru 2tl27). 



and terminated by a delimiter. 

Additional information concerning these conversions may be obtained from 
the TENEX JSYS Manual. 
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3.1.4 Lists 



The input syntax for • list is a soquenct (at Itast ona)'*^ of INTERLISP data 
elements, e.g. literal atoms numbers, other lists, etc. enclosed in 
parentheses or brackets. A bracket can be used to terminate several lists* 
e.g. (A (B (C], as described in Section 2. 

If there are two or more elements in a list, the final element can be preceded 
by a . (delimited on both sides), indicating that cdr of the final node in the 
list is to be the element immediately following the ., e.g. (A . B) or 
(ABC . D), otherwise cdr of the last node in a list will be NIL.^^ Note that 
the input sequence (ABC. NIL) is thus equivalent to (A B C), and that (A B . 
(C 0)) is thus equivalent to (A B C D). Note however that (A B . C 0) will 
create a list containing the five literal atoms A B . C and D. 

Lists are constructed by the primitive functions cons and list . 

Lists are printed by printing a left parenthesis, and then printing the first 
element of the list,^^ then printing a space, then printing the second element, 
etc. until the final node is reached. Lists are considered to terminate when 
cdr of some node is not a list. If cdr of this terminal node is NIL (the uiual 
case), car of the terminal node is printed followed by a right parenthesis. If 
cdr of the terminal node is not NIL, car of the terminal node is printed. 



() is read as the atom NIL. 

Note that in INTERLISP terminology, a list does not have to end in NIL, it 
is simply a structure composed of one or more conses. 

The individual elements of a list are printed using prinZ if the list is 
being printed by print or prin2 . and by print if the list is being printed 
by print . 
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followed by a space, a period, another space, cdr of the terminal node, and 
then the right parenthesis. Note that a list input as (A B C . NIL) will print 
as <A B C), and a list input as (A B . (C D)) will print as (A B C 0). Note 
also that printlevel affects the printing of lists to teletype, and that 
carriage returns may be inserted where dictated by linelength . as described in 
Section 14. 

A list is stored as a chain of list nodes, A list node is stored in one 36 bit 
word, the right half containing (^ar of the list (a pointer to the first element 
of the list), and the left half containing cdr of the list (a pointer to the 
next node of the list). 

3 . 1 . S Arrays 

An array in INTERLISP is a one dimensional block of contiguous storage of 
arbitrary length. Arrays do not have input syntax; they can only be created by 
the function array . Arrays are printed by both print , prin2 , and prinl , as # 
followed by the address of the array pointer (in octal). Array elements can be 
referenced by the functions elt and eltd, and set by the functions seta and 
setd, as described in Section 10.. 

Arrays are partitioned into four sections: a header, a section containing 
unboxed numbers, a section containing INTERLISP pointers, and a section 
containing relocation information. The last three sections can each be of 
arbitrary length (including 0); the header is two words long and contains the 
length of the other sections as indicated in the diagram below. The unboxed 
number region of an array is used to store 36 bit quantities that are not 
INTERLISP pointers, and therefore not to be chased from during garbage 
collections, e.g. machine instructions. The relocation informaion is used when 
the array contains the definition of a compiled function, and specifies which 
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locations in the unboxed region of the Array oust be changed if the array is 
moved during a garbage collection. 



The format of an array is as follows: 



HEADER WORD 0 
WORD I 

FIRST DATA WORD 



ADDRESS OF RELOCATION 
INFORMATION 


LENGTH 


USED BY GARBAGE 
COLLECTOR 


ADDRESS OF POINTERS 



NON-POINTERS 



POINTERS 



RELOCATION 
INFORMATION 



FIGURE 3-2 

The header contains: 

word 0 right - length of entire blocksARRAYSIZE-fZ. 

left - address of relocation information relative to word 0 of 
block (> 0 if relocation information exists, negative 
if array is a hash array, 0 if ordinary array). 

word 1 right * address of pointers relative to word 0 of block. 

left - used by garbage collector. 



3.1.6 Strings 



The input syntax for a string is a "» followed by a sequence of any characters 
except " and X, terminated by a " and X may be included in a string by 
preceding them with the escape character X. 
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strings are printed by print and prlnZ with initial and final "*s, and X*s 
inserted where necessary for it to read back in properly. Strings are printed 
by prinl without the delimiting '"*s and extra X's. 



Strings are created by mkstring . substring , and concat. 

Internally a string is stored in two parts; a string pointer and the sequence 
of characters. The INTERLISP pointer to a string is the address of the string 
pointer. The string pointer, in turn, contains the character position at which 
the string characters begin, and the number of characters. String pointers and 
String characters are two separate data types, and several string pointers 
may reference the same characters. This method of storing strings permits the 
creation of a substring by creating a new string pointer, thus avoiding copying 
of the characters. For more details, see Section 10. 

String characters are 7 bit bytes packed 5 to a word. The format of a string 
pointer is: 



^ OF CHARACTERS 



5 * ADDRESS OF STRING + CHARACTER 
POSITION 



14 15 35 
FIGURE 3-3 



The maximum length of a string is dZIC (Kal024) characters. 



13 

String characters are not directly accessible by user programs. 
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3.2 Storage Allocation and Garbaoe Collection 



In the following discussion* we will speak of a quantity of memory being 
assigned to a particular data type, meaning that the space is reserved for 
storage of elements of that type. Allocation will refer to the process used 
to obtain from the already assigned storage a particular location for storing 
one data element. 

A small amount of storage is assigned to each data type when IKITERLISP is 
started; additional storage is assigned only during a garbage collection. 

The page is the smallest unit of memory that may be assigned for use by a 
particular data type. For each page of memory there is a one word entry in a 
type table. The entry contains the data type residing on the page as well as 
other information about the page. The type of a pointer is determined by 
examining the appropriate entry in the type table. 

Storage is allocated as is needed by the functions which create new data 
elements, such as cons , pack , mkstrlng . For example, when a large integer is 
created by Iplus , the integer is stored in the next available location in the 
space assigned to integers. If there is no available location, a garbage 
collection is initiated, which may result in more storage being assigned. 

The storage allocation and garbage collection methods differ for the various 
data types. The major distinction is between the types with elements of fixed 
length and the types with elements of arbitrary length. List nodes, atoms, 
large integers, floating point numbers, and string pointers are fixed length; 
all occupy 1 word except atoms which use 3 words. Arrays, pnames, and strings 
(string characters) are variable length. 

Elements of fixed length types are stored so that they do not overlap page 
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boundaries. Thus the pages assigned to a fixed length type need not be 
adjacent. If more space is needed, any empty page will be used. The method of 
onocottfig storage for these types employs a free-list of available locations; 
that is, each available location contains a pointer to the next available 
location. A new element is stored at the first location on the free-list, and 
the free-list pointer is updated. 

Elements of variable length data types are allowed to overlap page boundaries. 
Consequently all pages assigned to a particular variable length type must be 
contiguous. Space for a new element is allocated following the last space used 
in the assigned block of contiguous storage. 

When INTERLISP is first called, a few pages of memory are assigned to each data 
type. Vftien the allocation routine for a type determines that no more space is 
available in the assigned storage for that type, a garbage collection is 
initiated. The garbage collector determines what data is currently in use and 
reclaims that which is no longer in use. A garbage collection may also be 
initiated by the user with the futjction reclaim (Section 10). 

Data in use (also called active data) is any data that can be * reached* from 
the currently running program (i.e., variable bindings and functions in 
execution) or from atoms. To find the active data the garbage collector 
'chases' all pointers, beginning with the contents of the push-down lists and 
the components (i.e., car, cdr, and function definition cell) of all atoms with 
at least one non-trivial component. 



The allocation routine for list nodes is more complicated. Each page 
containing list nodes has a separate free list. First a page is chosen 
(see CONS for details), then the free list for that page is used. Lists 
are the only data type which operate this way. 
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When a previously unmarked datum is encountered, it is marked, and all pointers 
contained in it are chased. Nost data types are marked using bit tables; that 
is tables containing one bit for each datum. Arrays, however, are narked using 
a half-word in the array header. 

When the mark and chase process is completed, unmarked (and therefore unused) 
space is reclaimed. Elements of fixed length types that are no longer active 
are reclaimed by adding their locations to the free-list for that type. This 
free list allocation method permits reclaiming space without moving any data, 
thereby avoiding the time consuming process of updating all pointers to moved 
data. To reclaim unused space in a block of storage assigned to a variable 
length type, the active elements are compacted toward the beginning of the 
storage block, and then a scan of all active data that can contain pointers to 
the moved data is performed to update the pointers. 

Whenever a garbage collection of any type is initiated,''^ unused space for all 
fixed length types is reclaimed since the additional cost is slight. However, 
space for a variable length type is reclaimed only when that type initiated the 
garbage collection. 

If the amount of storage reclaimed for the type that initiated the garbage 
collection is less than the minimum free storage requirement for that type, the 
garbage collector will assign enough additional storage to satisfy the minimum 
free storage requirement. The minimum free storage requirement for each data 
may be set with the function minfs (Section 10). The garbage collector assigns 
additional storage to fixed length types by finding empty pages, and adding the 
appropriate size elements from each page to the free list. Assigning 



The 'type of a garbage collection' or the 'type that initiated a garbage 
collection' means either the type that ran out of space and called the 
garbage collector, or the argument to reclaim . 
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additional storage to a variable length type involves finding empty pages and 
moving data so that the empty pages are at the end of the block of storage 
assigned to that type. 

In addition to increasing the storage assigned to the type initiating a garbage 
collection, the garbage collector will attempt to minimize garbage collections 
by assigning more storage to other fixed length types according to the 
following algorithm.'^ If the amount of active data of a type has Increased 
since the last garbage collection by more than 1/4 of the minfs value for that 
type» storage is increased (if necessary), to attain the minfs value. If 
active data has increased by less than 1/4 of the minfs value, available 
storage is , increased to 1/2 minfs . If there has been no increase, no more 
storage is added. For example, if the minfs setting is 2000 words, the number 
of active words has increased by 700, and after all unused words have been 
collected there are 1000 words available, 1024 additional words (two pages) 
will be assigned to bring the total to 2024 words available. If the number of 
active words had increased by only 300, and there were 500 words available, 512 
additional words would be assigned. 

3.3 Shared INTERLISP 

The INTERLISP system initially obtained by the user is shared; that is, all 
active users of INTERLISP are actually using the same pages of memory. As a 
user adds to the system, private pages are added to his memory. Similarly, if 
the user changes anything in the original shared INTERLISP, for example, by 
advising a system function, a private copy of the changed page is created. 



We may experiment with different algorithms. 
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In addition to the swapping tine saved by having several users accessing the 
same nemory, the sharing mechanism permits a large saving in garbage collection 
time, since we do not have to garbage collect any data in the shared system, 
and thus do not need to chase from any pointers on shared pages during garbage 
collections. 

This reduction in garbage collection time is possible because the shared system 
usually is not modified very much by the user. If the shared system is changed 
extensively, the savings in time will vanish, because once a page that was 
initially shared is made private, every pointer on it must be assumed active, 
because it may be pointed to by something in the shared system. Since every 
pointer on an initially shared but now private page can also point to private 
data, they must always be chased. 

A user may create his own shared system with the function makesys . If several 
people are using the same system, making the system be shared will result in a 
savings in swapping time. Similarly, if a system is large and seldom modified, 
making it be shared will result in a reduction of garbage collection time, and 
may therefore be worthwhile even if the system is only being used by one user. 

makesysCf lie] creates a saved file in which all pages in this 

system, including private user pages, are made 
read execute, i.e. shared. This system can then 
be run via the TENEX Command RUN, or GET and 
START. 

For example, new INTERLISP systems are brought up by loading the appropriate 
compiled files and then performing makesysCLISP.SAV].^^ 



makesys is also advised to set the variable makesysdate to (DATE), i.e. the 
time and date the system was made. 
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Page 
Numbers 

ARRAY[N;P;V] SUBR 3.8 

array header , 3.8 

array pointer 3.8 

arrays 3.1,8,11,13 

atoms 3.1»11 

carriage-return , 3.2 

compacting 3.13 

C0NCATCXl;X2;...;Xn] SUBR* 3.10 

CONSCX;Y] SUBR 3.7,11 

data types 3.1-11 

E (In a floating point number) 3.6 

ELT[A;N] SUBR 3.8 

ELTD[A;N3 SUBR 3.8 

end-of-line 3.2 

EOPCX;Y] SUBR 3.5 

escape character 3.2 

floating point numbers 3.1,4,6,11 

FLTFMTCN] SUBR 3.6 

free-list 3.12-13 

function definition cell 3.3 

garbage collection 3.11-14 

GENSYMCCHAR] 3.2 

hash arrays 3.1 

integers 3.4 

large integers 3.1,5,11 

line-feed 3.2 

LINELENGTHCN] SUBR 3.8 

LIST[Xl;X2;...;Xn] SUBR* 3.7 

list nodes 3.8,11 

lists , 3.1,7 

literal atoms 3.2-3 

MAKESYS[FILE] EXPR 3.15 

MAKESYSDATE (system variable/parameter) 3.15 

MINFS[N;TYP] SUBR 3.13-14 

MKATOMCX] SUBR 3.2.5-6 

MKSTRINGCX] SUBR 3.10-11 

NOBIND 3.3 

octal 3.5,8 

PACKCX] SUBR 3.2,5-6,11 

page 3.11 

pname cell 3.3 

pnames 3.1-4,11 

pointer 3.1 

PRIN1[X;FILE] SUBR 3.2,8.10 

PRIN2CX;FILE] SUBR 3.2,8.10 

PRINT[X;FILE] SUBR 3.2,8,10 

PRINTLEVELCN] SUBR 3.8 

private pages 3.15 

property list • 3.3 

Q (following a number) 3.5 

RADIX[N] SUBR 3.5 

RECLAIM[N] SUBR 3.12-13 

relocation information (in arrays) 3.8 

RUN (tenex command) 3.15 

SETA[A;N;V] 3.8 

SETD[A;N;V] 3.8 
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shared pages , 3.19 

shared system 3.15 

sharing 3.19 

small integers 3.1,9 

SMALLP[N] 3.S 

space 3.2 

storage allocation 3.11 

string characters 3.1,10-11 

string pointers ...^ * 3.1, 10-11 

strings 3.10 

SUBSTRING[X;N;N] SUBR 3.10 

TENEX 3.2,6,19 

unboxed numbers (in arrays) 3.0 

" , 3.2,10 

# (followed by a number) 3.8 

X (escape character) 3.2,10 

( 3.2 

() 3.7 

) 3.2 

3.7 

. (in a floating point number) 3.6 

C 3.2 

] , 3.2 
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SECTION 4 
FUNCTION TYPES AND IMPLICIT PROGN 



In INTERLISP, each function may independently have: 
a. its arguments evaluated or not evaluated; 

b* a fixed number of arguments or an indefinite number of arguments; 
c. be defined by an INTERLISP expression, by built-in machine code» or by 
compiled machine code. 

Hence there are twelve function types (2x2x3). 
4 . 1 Exprs 

Functions defined by INTERLISP expressions are called exprs . Exprs must begin 
with either LAMBDA or NLAMBDA,^ indicating whether the arguments to the 
function are to be evaluated or not evaluated, respectively. Following the 
LAMBDA or NLAM60A in the expr is the 'argument list*, which is either 

(1) a list of literal atoms or NIL (fixed number of arguments); or 

(2) any literal atom other than NIL* (indefinite number of arguments). 

Case (1) corresponds to a function with a fixed number of arguments. Each atom 
in the list is the name of an argument for the function defined by this 



Where unambiguous, the term expr is used to refer to either the function, 
or its definition. 
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expression. When the function Is called, its arguments will be evaluated or 
not evaluated, as dictated by whether the definition begins with LAMBDA or 
NLANBDA, and then paired with these argument names. This process is called 
"spreading" the arguments, and the function is called a spread-LAMBDA or a 
spread-NLANBDA. 

Case (2) corresponds to a function with an indefinite number of arguments*. 
Such a function is called a nospread function. If its definition begins with 
NLAMBDA, the atom which constitutes its argument list is bound to the list of 
arguments to the function (unevaluated). For example, if FOO is defined by 
(NLAMBDA X — ), when (FOO THIS IS A TEST) is evaluated, X will be bound to 
(THIS IS A TEST). 

If a nospread function begins with a LAMBDA, indicating its arguments are to be 
evaluated, each of its n arguments are evaluated and their values stored on the 
pushdown list. The atom following the LAMBDA is then bound to the number of 
arguments which have been evaluated. For example, if FOO is defined by 
(LAMBDA X --) when (FOO ABC) is evaluated. A, B, and C are evaluated and X is 
bound to 3. A built-in function, argCatm;m], is available for computing the 
value of the mth argument for the lambda-atom variable atm. arg is described 
in section 8. 

4.2 Compiled Functions 

Functions defined by expressions can be compiled by the INTERLISP compiler, as 



Note that the function itself can evaluate selected arguments by calling 
eval » In fact, since the function type can specify only that all arguments 
are to be evaluated or none are to be evaluated, if it is desirable to 
write a function which only evaluates some of its arguments, e.g. setq . the 
function is defined as an nlambda, i.e. no arguments are evaluated in the 
process of calling the function, and then included in the definition itself 
are the appropriate calls to eval . 
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described in section 16» "The Compiler and Assembler". Functions may also be 
written directly in machine code using the ASSEMBLE directive of the compiler. 
Functions created by the compiler , whether from 5-expressions or ASSEMBLE 
directives, are referred to as compiled functions. 

4.3 Function Type 

The function fntyp returns the function type of its argument. The value of 
fntyp is one of the following 12 types: 



EXPR 
FEXPR 
EXPR* 
FEXPR* 



CEXPR 
CFEXPR 
CEXPR* 
CFEXPR* 



SUBR 
FSUBR 
SUBR* 
FSUBR* 



The types in the first column are all defined by expressions. The types in the 
second column are compiled versions of the types in the first column, as 
indicated by the prefix C. In the third column are the parallel types for 
built-in subroutines. Functions of types in the first two rows have a fixed 
number of arguments, i.e., are spread functions. Functions in the third and 
fourth rows have an indefinite number of arguments, as indicated by the 
suffix *. The prefix F indicates no evaluation of arguments. Thus, for 
example, a CFEXPR* is a compiled form of a nospread-NLAMBDA. 



A standard feature of the INTERLISP system is that no error occurs if a spread 
function is called with too many or too few arguments . If a function is called 
with too many arguments , the extra arguments are evaluated but ignored. If a 
function is called with too few arguments , the unsupplied ones will be 
delivered as NIL, In fact, the function itself cannot distinguish between 
being given NIL as an argument, and not being given that argument ^ e.g., 
(FOO) and (FOO NIL) are exactly the same for spread functions. 



4.3 



4.4 Progn 



progn is a function of an arbitrary number of arguments, progn evaluates the 
arguments in order and returns the value of the last, i.e., it is an extension 
of the function progZ of LISP 1,5. Both cond and lambda /n lambda expressions 
have been generalized to permit 'implicit progns* as described below. 

4.5 Implicit Progn 

The conditional expression has been generalized so that each clause may contain 
n forms (n > 1) which are interpreted as follows: 

(COND 

(PI Ell E12 Eld) 

(P2 E21 E22) [1] 
(P3) 

(P4 E41)) 

will be taken as equivalent to (in LISP 1.5): 



(COND 

(PI (PROGN EU E12 E13)) 

(P2 (PROGN E21 E22)) 

(P3 P3) [2] 

(P4 E41) 

(T NIL)) 



Note however that P3 is evaluated only once in [1], while it is evaluated a 
second time if the expression is written as in [2]. Thus a clause in a cond 
with only a predicate and no following expression causes the value of the 
predicate itself, if non-NIL, to be returned. Note also that NIL is returned 
if all the predicates have value NIL, i.e., the cond 'falls off the end*. No 
error is generated. 



LAMBDA and NLAMBDA expressions also allow implicit progn *s; thus for example: 
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(LAMBDA (VI V2) (Fl VI) (F2 V2) NIL) 



is interpreted as: 

(LAMBDA (VI V2) (PROGN (Fl VI) (F2 V2) NIL)) 

The value of the last expression following LAMBDA (or NLAMBOA) is returned as 
the value of the entire expression. In this example, the function would always 
return NIL. 
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Numbers 

ARG[VAR;M] FSUBR 4.2 

argument evaluation 4.1-2 

argument list 4.1 

ASSEMBLE 4.3 

CEXPR (function type) 4.3 

CEXPR* (function type) 4.3 

CFEXPR (function type) 4.3 

CFEXPR* (function type) 4.3 

compiled functions 4.2 

compiler 4.3 

C0ND[C1;C2;.. .;Cn] FSUBR* 4.4 

EVALCX] SUBR 4.2 

EXPR (function type) 4.3 

EXPR* (function type) 4.3 

exprs 4.1 

FEXPR (function type) 4.3 

FEXPR* (function type) 4.3 

fixed number of arguments 4.1 

FNTYP[X] .. 4.3 

FSUBR (function type) 4.3 

FSUBR* (function type) 4.3 

function types 4.1-3 

implicit progn 4.4 

incorrect number of arguments 4.3 

indefinite number of arguments 4.2 

LAMBDA 4.1-2,4 

NLAMBDA 4.1-2,4 

nospread functions 4.2 

PR0GN[Xl;X2;...;Xn] FSUBR* 4.4 

pushdown list 4.2 

spread functions 4.2 

spreading arguments 4.2 

SUBR (function type) 4.3 

SUBR* (function type) 4.3 

too few arguments 4.3 

too many arguments 4.3 
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SECTION 5 
PRIMITIVE FUNCTIONS AND PREDICATES 



5«1 Primitlv Functions 

car[x] car gives the first element of a list x, or the 

left element of a dotted pair x* literal 
atom, value is top level binding (value) of the 
atom. For all other nonlists, e.g. strings, 
arrays, and numbers, the value is undefined, i.e., 
it is the right 18 bits of x. 



cdr[x] 



cdr gives the rest of a list (all but the first 
element). This is also the right member of a 
dotted pair. If x is a literal atom, cdr[x3 gives 
the property list of x. Property lists are 
usually NIL unless modified by the user. The 
value of cdr is undefined for other nonlists, i.e. 
it is the left 18 bits of x. 



caar[x] « car[car[x]3 
cadr[x] « car[cdr[x3] 
cddddrCx] « 
cdr[ cdr[ cdrC cdrC x] 3 3 3 



All 30 combinations of nested cars 
and cdrs up to 4 deep are included 
in the system. All are compiled 
open by the compiler. 



cons[x;y3 



cons constructs a dotted pair of x and 2. If y is 
a list, X becomes the first element of that list. 
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To minimize drum accesses the following algorithm 
is used for finding a page on which to put the 
constructed INTERLISP word. 



cons[x;y] is placed 

1) on the page with ;^ if ^ a list and there is room; 
otherwise 

2) on the page with x if x is a list and there is room; 
otherwise 

3) on the same page as the last cons if there is room; 
otherwise 

4) on any page with a specified minimum of storage* presently 16 LISP 
words . 

conscount[] value is the number of cons es since this INTERLISP 

was started up. 

rplacdCx;y] Places the pointer y. decrement, i.e. cdr , 

of the cell pointed to by x* Thus it physically 
changes the internal list structure of x, as 
opposed to cons which creates a new list element. 
The only way to get a circular list is by using 
rplacd to place a pointer to the beginning of a 
list in a spot at the end of the list. 

The value of rplacd is x* An attempt to rplacd 
NIL will cause an error, ATTCNPT TO RPLAC NIL, 
(except for rplacd[NIL;NIL]). For x a literal 
atom, rplacd[x;y] will make y. property list 

of X* For all other non-lists, rplacd should be 
used with care: it will simply store ^ in the left 
16 bits of X. 
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rplaca[x;y] similar to rplacd . but replaces the address 

pointer of x» !•••> car* with The value of 
rplaca is x. An attempt to rplaca NIL will cause 
an error, ATTEMPT TO RPLAC NIL, (except for 
rplaca[NIL;NIL]) . For x a literal atom, 
rplacaCx;y] will make ^ be the top level value for 
X. For all other non-lists, rplaca should be used 
with care: it will simply store ^ in the right 18 
bits of X. 



Conuentioni Naming o function by prefixing an existing function name with £ 
usual lu indicates that the new function is a fast version of the 
old, i.e.. one which has the same definition but compiles open and 
runs without any * safety* error checks. 



frplacdCx;y] 



Has the same definition as rplacd but compiles 
open as one instruction. Note that no checks are 
made on x» so that a compiled frplacd can clobber 
NIL, producing strange and wondrous effects. 



frplaca[x;y] 



Similar to frplacd . 



quote[x] 



This is a function that prevents its arguments 
from being evaluated. Its value is x itself, e.g. 

(QUOTE FOO) is FOO.^ 



kwoteCx] 



(LIST (QUOTE QUOTE) x), 

if x^^A, and ^sB, then 

(ICWOTE (CONS X y))« (QUOTE (A . B)) 



Since giving quote more than one argument, e.g. (QUOTE EXPR (CONS X Y)), is 
almost always a parentheses error, and one that would otherwise go 
undetected, quote itself generates an error in this case, 
PARENTHESIS ERROR. 
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cond[C|;c2; • • • ;c^l 



selectqCx;y^ ly^l . . . sy„;2] 



The conditional function of INTERLISP, cond . takes 
an indefinite number of arguments S^i^^^* "* ~k' 
called clauses. Each clause c^^ is a list (e^i^ ... 
§„^) of n > 1 items, where the first element is 
the predicate, and the rest of the elements the 
consequents. The operation of cond can be 
paraphrased as IF e^^ THEN e^^ ••• e^ii 

ELSEIF e|2 THEN ... e^^ ELSEIF 0^3 ... 

The clauses are considered in sequence as follows: 
the first expression e^^ of the clause c^ is 
evaluated and its value is classified as false 
(equal to NIL) or true (not equal to NIL). If the 
value of e^^ is true, the expressions e^^^ 
that follow in clause c^ are evaluated in 
sequence, and the value of the conditional is the 
value of e^^, the last expression in the clause. 
In particular, if nel, i.e., if there is only one 
expression in the clause c^, the value of the 
conditional is the value of g^^. (which is 
evaluated only once). 

If e^^ is false, then the remainder of clause c^ 
is ignored, and the next clause c^^^ is 
considered. If no e^^ is true for any clause, the 
value of the conditional expression is NIL. 

selects a form or sequence of forms based on the 
value of its first argument x* Each is a list 
of the form (s^ e^^ e^i *** iki^ where s^ is the 
selection key. The operation of selectq can be 
paraphrased as: 
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IF x«Sj THEM ej^ ... e,^^ 
ELSEIF x-s^ THEN ... ELSE z. 

If is an atom* the value of x is tested to see 
if it is §3 to (not evaluated). If so, the 
expressions e^^ ... are evaluated in sequence, 
and the value of the selectq is the value of the 
last expression evaluated, i.e. Oj^^. 

If s^ is a list, the value of x is compared with 
each element (not evaluated) of s^, and if x is eg 
to any one of them, then e^^ to e|^^ are evaluated 
in turn as above. 

If is not selected in one of the two ways 
described, ^.^^i tested, etc., until all the ^'s 
have been tested. If none is selected, the value 
of the selectq is the value of z. z must be 
present. 

An example of the form of a selectq is : 

[SELECTQ (CAR X) 

(0 (PRINT FOO) 

(FIE X)) 
((A E I 0 U) 
(VOWEL X)) 
(COND 

((NULL X) 

NIL) 
(T (QUOTE STOP] 

which has two cases, Q and (A E I 0 U) and a 
default condition which is a cond. 



selectq compiles open, and is therefore very fast; 
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proglCXj;X2;...;x„] 



progn[Xj^;x2i;...;X|^] 



progCargs; 0^:62; • • • 



howover, it will not work if the value of x is a 
list, a large integer, or floating point number, 
since selectq uses eg for all comparisons. 

evaluates its arguments in order, that is, first 
Xj, then X2> ®^^> returns the value of its 
first argument x^f e.g. (PROGl X (SETQ X Y)) sets 
X to 2* And returns x's original value. 

progn evaluates each of its arguments in order, 
and returns the value of its last argument as its 
value, progn is used to specify more than one 
computation where the syntax allows only one, e.g. 
(SELECTQ ... (PROGN ...)) allows evaluation of 
several expressions as the default condition for a 
selectq . 

This function allows the user to write an ALGOL- 
like program containing INTERLISP expressions 
(forms) to be executed. The first argument, args , 
is a list of local variables (must be NIL if no 
variables are used). Each atom in args is treated 
as the name of a local variable and bound to NIL. 
args can also contain lists of the form 
(atom form). In this case, atom is the name of 
the variable and is bound to the value of form . 
The evaluation takes place before any of the 
bindings are performed, e.g., 

(PROG ((X Y) (Y X)) ...) will bind x to the value 
of 2 and X to the (original) value of x. 
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The r«st of the prog is a sequence of non-atomic 
statements (forms) and atomic symbols used as 
labels for go. The forms are evaluated 
sequentially; the labels serve only as markers. 
The two special functions go and return alter this 
flow of control as described below. The value of 
the prog is usually specified by the function 
return . If no return is executed, i.e., if the 
prog "falls off the end," the value of the prog is 
undefined, i.e. garbage. 

go[x] go is the function used to cause a transfer in a 

prog . (60 L) will cause the program to continue 
at the label L. A go can be used at any level in 
a prog . If the label is not found, go will search 
higher progs within the same function, e.g. 
(PROG — A (PROG (GO A))). If the label is 
not found in the function in which the prog 
appears, an error is generated, UNDEFINED OR 
ILLEGAL GO. 

returnCx] A return Is the normal exit for a prog . Its 

argument Is evaluated and Is the value of the prog 
In which It appears. 

If o go or return is executed in an interpreted function which is not a prog , 
the go or return will be executed in the last interpreted proa entered if any, 
otherwise cou^e an error, 

go or return inside of a compiled function that is not a prog is not allowed, 
and will cause an error at compile time. 

As a corollary, go or return in a functional argument, e.g. to mapc . will not 
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work compiled. Also, since inlsetq 's and ersetq 's compile as separate 
functions, a go or return cannot be used inside of a compiled nlsetq or ersetq 
if the corresponding prog is outside, i.e. above, the nlsetq or ersetq . 

set[x;y] Thl» function sets x to Its value is If x 

is not a literal atom, causes an error, 
ARG NOT ATON - SET. If x is NIL, causes an error, 
ATThlNPT TO SET NIL. Note that set is a normal 
lambda-spread function, i.e., its arguments are 
evaluated before it is called. Thus, if the value 
of X is c, and the value of ^ is b, then set[x;y] 
would result in c having value b, and b being 
returned as the value of set. 



setqCx;y] An n lambda version of set : the first argument is 

not evaluated, the second is.^ Thus if the value 
of X is C and the value of Y is B, (SETQ X Y) 
would result in X (not C) being set to B, and B 
being returned. If x ^ literal atom, an 

error is generated, ARG NOT ATON - SET. If x is 
NIL, the error ATTENPT TO SET NIL is generated. 

setqqCx;y] Like setq except that neither argument is 

evaluated, e.g. (SETQQ X (A B C)) sets x to 
(A B C). 



Since setq is an nlambda, neither argument is evaluated during the calling 
process. However, setq itself calls eval on its second argument. Note 
that as a result, typing (SETQ var form) and SETQ(var form) to lispx is 
equivalent: in both cases yar is not evaluated, and form is. 
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rpaq[x;y] like setq , oxctpt always works on top level 

binding of x, i.e. on the value cell. rpaq 
derives its name from r^laca fluote, since it is 
essentially an nlambda version of rplaca , e.g. 
(RPAQ FOO form) is equivalent to 

(RPLACA (QUOTE FOO) form). 

rpaqq[x;y3 like setqq for top level bindings. 

rpaq and rpaqq are used by prettydef (Section 14). Both rpaq and rpaqq 
generate errors if x is not atomic. Both are affected by the value of dfnf Ig 
(Section 8). If dfnflq » ALLPROP (and the value of x is other than NOBINO), 
Instead of setting x> the corresponding value is stored on the property list of 
X under the property VALUE. 

Resetvar and Resetform 

resetvarCvar; new-value; from] The effect of resetvar is the same as 

(PROG ((var new-value)) (RETURN form)), except 
that resetvar is designed to work on GLOBAL 
variables, i.e. variables that roust be reset, not 
rebound (see section 18). resetvar resets the 
variable (using frplaca ), and then restores its 
value after evaluating form . The evaluation of 
form is errorset protected so that the value is 
restored even if an error occurs, resetvar also 
adds the old value of var to a global list, so 



In this case, after restoring the value, resetvar propagates the error 
backwards by calling error! . 
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that If the user types Control-D (or Control-C 
followed by REENTER) while form is being 
evaluated, the variable will be restored by the 
top level INTERLISP executive. The value of 
res'Stvar is the value returned by form , resetvar 
compiles open. 

For example, the editor calls lispx to execute editor history 
commands by performing (RESETVAR LISPXHISTORY EDITHISTORY (LISPX — )), thereby 
making lispx work on edithistory instead of lispxhistory . 

The behavior of many system functions is affected by Calling certain functions, 
as opposed to resetting variables, e.g. printlevel . linelength . input , output . 
radix , gcgag . etc. The function resetform enables a program to treat these 
functions much like variables, and temporarily change their "setting". 

resetform[forml;form2] nlainbda, nospread, forrol is evaluated, then formZ 

is evaluated, then forrol is * restored', e.g. 
(RESETFORM (RADIX 6) (FOO)) will evaluate (FOO) 
while radix is 8, and then restore the original 
setting of radix. 

fonnl must return as its value its "previous 
setting" so that its effects can be undone by 
applying car of forrol to this value. 

resetform is errorset protected like resetvar , and 
also records its information on a global list so 
that after control-D (or control-C REENTER), forml 
is properly restored. 
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The valuo of rtsetforin is tht valu« returned by 
formZ . resetfona compiles open. 

5.2 Predicates and Logical Connectives 

atonCx] is T If X is an atom; NIL otherwise. 

litatomCx] is T if x is a literal atom, i.e., an atom and not 

a number, NIL otherwise. 

numberpCx] is x if x is a number, NIL otherwise. 

Conventiont Functions that end in £ are usual Iff predicates » i.e. they test for 
some condition, 

stringp[x] is x if x is a string, NIL otherwise.^ 

arraypCx] is x if x is an array, NIL otherwise. 

listpCx] is X if X is a list-structure, i.e., one created 

by one or more conses ; NIL otherwise. 

Hfote thdt arrays and strings are not atoms ^ but are also not lists, i.e. both 
atom and I is to will return MIL when given an array or a string, 

nlistpCx] not[listp[x]] 

oq[x;y] The value of eg is T, if x and x '^''e pointers to 

^ For other string functions, see Section 10. 
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the sane structure in memory, and NIL otherwise, 
e^ is compiled open by the compiler as a 36 bit 
compare of pointers. Its value is not guaranteed 
T for equal numbers which are not snail integers. 
See eqp . 



neq[x;y] The value of nes[ is T, if x is not e^ to and 

NIL otherwise. 

null[x] eqCx;NIL] 

notCx] same as null , that is eq[x;NIL]. 

eqp[x;y] The value of egg is T if x and £ are e^, i*o« 

pointers to the same structure in memory, or if x 
and Y. are numbers and are equal. Its value is NIL 
otherwise.^ 

equal[x;y] The value of this function is T if x and ^ print 

identically; the value of equal is NIL otherwise. 
Note that x and ^ do not have to be eg. 

andCX|;x2; . . . ;X|^] Takes an indefinite number of arguments (including 

0). If all of its arguments have non-null value, 
its value is the value of its last argument, 
otherwise NIL. E.g. and[x;member[x;y]] will have 
as its value either NIL or a tail of y,' andC]sT. 
Evaluation stops at the first argument whose value 
is NIL. 



^ For other number functions, see Section 13. 
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orCX|;X2; • • • ;X|^] Takes an indefinite number of arguments (including 

0). Its value is that of the first argument whose 
value is not NIL, otherwise NIL if all arguments 
have value NIL. E.g. or[x;numberp[y]] has its 
value x» or NIL. orC]sNIL. Evaluation stops at 
the first argument whose value is not NIL. 

everyCeveryx;everyfnl;everyfn2] Is T if the result of applying everyfni 

to each element in everyx is true, otherwise NIL. 
E.g.. every[(X Y Z); AT0M3-T. 

every operates by computing 

everyfnlCcarC everyx]].^ If this yields NIL, every 
immediately returns NIL. Otherwise, every computes 
everyfn2[ everyx], or cdr[everyx] if everyfnZ sNIL, 
and uses this as the 'new' everyx , and the process 
continues, e.g. every[x;ATON;CD0R] is true if 
every other element of x is atomic. 

every compiles open. 

someCsomex;soroefnl;somefn2] value is the tail of somex beginning with the 

first element that satisfies somefnl, i.e., for 

which somefnl applied to that element is true. 

Value is NIL if no such element exists. 

E.g., someCx;(LAHBDA (Z) (EQUAL Z Y))] is 

equivalent to member[y;x]. some operates 



Actually, everyfnl[car[ everyx] ;everyx] is computed, so for example everyfni 
can look at the next element on everyx if necessary. 
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analagously to every . At each stage, 

soniefnlCcar[soiaex];somex] is computed, and if this 
is not NIL, somex is returned as the value of 
some . Otherwise, some fn2[ somex] is computed, or 
cdr[ somex] if somefnZsNIL, and used for the next 
some x. 

some compiles open. 
notanyC somex ;somefnl,somefn2] same as not[some[somex;somefnl;somefn2]] 
noteveryCeveryx;everyfnl ;everyfn2] not[everyCeveryx;everyfnl ;everyfn2]] 



memb[x;y] 



Determines if x is a member of the list i.e., 
if there is an element of esi to x. If so, its 
value is the tail of the list ^ starting with that 
element. If not, its value is NIL. 



fmerob[x;y] 



Fast version of memb that compiles open as a five 
instruction loop, terminating on a NULL check. 
Interpreted, fmemb gives an error, 
BAD ARGUMENT - FNENB, if ^ ends in a non-list 
other than NIL. 



merober[x;y] 



Identical to memb except that it uses equal 
instead of eg. to check membership of x in 



The reason for the existence of iboth memb and member is that compiles as one 
instruction but equal requires cf function caH, and is therefore considerably 
more expensiue. Wherever possible, the user should write (and use) functions 
that use e£ instead of equal . 
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tallp[x;y3 



Is X, if X is « list and a tail of y.* i*e.> x is 
eg to soM nunbar of cdrs > 0^ of y.* 
otharwisa. 



assoc[x;y] 



X is a list of lists (usually dottad pairs). The 
value of assoc is the first sublist of ^ ^^os9 car 
is eg to X- If such a list is not found, the 
value is NIL. Example: 

assocCB;((A . 1) (B . 2) (C . 3))] ■ (B . 2). 



fassoc[x;y] 



Fast version of assoc that compiles open as a 6 
instruction loop, terminating on a NULL check. 
Interpreted, fassoc gives an error if x. ^^^^ ^ 
non-list other than NIL, BAD ARGUMENT - FASSOC. 



sassoc[x;y] 



Same as assoc but uses equal instead of e^i. 



If X is 6£ to some number of cdrs > 1 of we say x is a proper tail. 
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SECTION 6 
LIST MANIPULATION AND CONCATENATION 



listCx^;X2;***iX„] 



appendrX|SX2;...;x^I 



laabda-flospread function. Its value is a list of 
the values of its arguments. 

Copies the top level of the list x^ end appends 
this to a copy of top level list X2 appended to 
... appended to x^t e.g. 

appendC(A B) (C D E) (F 6)] » (A B C D E F G). 
Note that only the first n-1 lists are copied. 
However n«l is treated specially; i.e. appendCx] 
can be used to copy the top level of a single 
list.^ 

The following exafflples illustrate the treatment of 
non-lists. 

appendC(A B C);D] » (A B C . 0) 
appendCA;(B C 0)] « (B C 0) 
append[(A B C . 0);(E F 6)] - (A B C E F G) 
appendC(A B C . D)] > (A B C . 0) 



To copy a list to all levels, use copy . 



nconc[X|;X2; • . • ;x^] Returns same value as append but actually nodifies 

the list structure of X| ... 

nconcl[lst;x] Perfoms nconcClst;list[x]]. The cons will be on 

the sane page as 1st. 

tconc[ptr;x] tconc is useful for building a list by adding 

elements one at a time at the end» i.e. its role 
is similar to that of ncdncl . However r unlike 
nconcl , tconc does not have to search to the end 
of the list each time it is called. It does this 
by keeping a pointer to the end of the list being 
assembled, and updating this pointer after each 
call. The savings can be considerable for long 
lists. The cost is the extra word required for 
storing both the list being assembled, and the end 
of the list. £tr is that word: car[ptr] is the 
list being assembled, cdr[ptr] is last [carCptr]]* 
The value of tconc is £tr, with the appropriate 
modifications to car and cdr. Example: 

-(RPTO 5 (SETO FOO TCONC FOO RPTN))) 
(<5 4 3 2 1) 1) 

tconc can be initialized in two ways. If ptr is 
NIL, tconc will make up a £tr. In this case, the 
program must set some variable to the value of the 
first call to tconc . After that, it is 
unnecessary to reset £tr since tconc physically 
changes it. Thus: 

^(SET FOO (TCONC NIL 1)) 
(d) 1) 

«-(RPTQ 4 (TCONC FOO RPTN)) 
((14 3 2 1) 1) 
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If £tr is initially (NIL), the value of tconc is 
the same as for ptr»NIL. but tconc changes ptr . 
e.g. 



IconcCptrix] 



«-(SETQ FOO (CONS)) 
(NIL) 

«-(RPTQ 5 (TCONC FOO RPTN)) 
((5 4 3 2 1) 1) 

The latter method allows the program to 
initialize* and then call tconc without having to 
perform setq on its value. 

Where tconc is used to add e£ements at the end of 
a listr Iconc is used for building a list by 
adding lists at the end, i.e. it is similar to 
nconc instead of nconct, e.g. 



-(SETQ FOO (CONS)) 
(NIL) 

«-(LCONC FOO (LIST 1 2)) 
((1 2) 2) 

••(LCONC FOO (LIST 3 4 5)) 
((12 3 4 5) 5) 
«-(LCONC FOO NIL) 
((12 3 4 5) 5) 

Note that 

•-(TCONC) FOO NIL) 
((12345 NIL) NIL) 
-(TCONC FOO (LIST 3 4 5)) 
((12345 NIL (3 4 5)) (3 4 5)) 



Iconc uses the same pointer conventions as tconc 
for eliminating searching to the end of the list, 
so that the same pointer can be given to tconc and 
Iconc interchangeably. 



attach[x;y] 



Value is equal to cons[x;y], but attaches x to the 
front of X by (loing an rplaca and rplacd . i.e. 
the value of attach is e£ to ^, which it 
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physically changes. ^ oust bt a list> or an arror' 
is generatad, ILLEGAl AR6. 



reiQOveCx;!] 



Removos all occurrences of x from list 1» giving a 
copy of 1 with all elements equal to x removed. 



Conventiont Warning a function by prefixing an existing function with d 
frequently indicates the new function is a crejtrifctiye ver^ioii of 
the old one, i.e. it does not make any new structure but 
cannibalizes its argment(s) . 



dreroove[x;l] 



Similar to remove , but uses eg instead of equal , 
and actually modifies the list 1 When removing x» 
and thus does not use any additional storage. 
More efficient than remove . 



copytx] 



Hakes a copy of the list x. The value of copy is 
the copied list. All levels of x are copied* 
down to non-lists, so that if x contains arrays 
and strings, the copy of x will contain the same 
arrays and strings, not copies. Copy is recursive 
in the car direction only, so that very long lists 
can be copied. 



reverse[l] 



Reverses (and copies) the top level of a list, 
e.g. reverse[(A B (C D))] - ((C 0) B A). If x is 
not a list, value is x* 



dreverseCl] 



Value is same as that of reverse, but dreverse 



To copy Just the top level of x, do appendCx]. 
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destroys the original list 1 and thus does not use 
any additional storage. More efficient than 
reverse. 



substCx;y;2] Value is the result of substituting the S- 

expression x for all occurrences of the S- 
expression ^ in the S-expression z. Substitution 
occurs whenever y is equal to car of sone 
subexpression of z, or when y. 1' both atonic and 
not NIL and sg to £dr of sone subexpression of z. 
For exanple: 

subst[A;B;(C B (X . B))] » (C A (X . A)) 
subst[A;(6 C);((6 C) 0 6 C)] « (A 0 B C), 
not (AD .A). 

The value of subst is a copy of z with the 
appropriate changes. Furthernore, if x is a list, 
it is copied at each substitution. 

dsubstCx;y;z] Sinilar to subst . but uses eg and does not copy z, 

but changes the list structure z itself. Like 
subst . dsubst substitutes with a copy of x* More 
efficient than subst. 

lsubst[x;y;z] Like subst except x is substituted as a segnent, 

e.g. lsubstC(A B);Y;(X Y Z)] is (X A B Z). Note 
that if X is NIL, produces a copy of z with all 
jr's deleted. 

esubst[x;y;z;flg] Sinilar to dsubst . but first checks to see if y. 

actually appears in z. If not, calls error! where 
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flgsT means print a nessage of the fom x 7 This 
function is actually an implenentation of the 
editor's R conmand (see Section 9), so that y. can 
use &, or alt-modes as with the R command. 

sublis[alst;expr;flg] alst is a list of pairs: 

((Uj . Vj) (Ug . Vg) ... (u^ . v^)) with each 
atomic . 



The value of sublisCalst;expr;flo] is the result 
of substituting each v for the corresponding In 
expr . Example: 

sublis[((A . X) (C . Y));(A B C D)] s <x B Y 0) 
New structure is created only if needed* or if 
flgsT. e.g. if flgsNIL and there are no 
substitutions, value is eg to expr . 

subpair[ old; new; expr; fig] Similar to sublis* except that elements of new ere 

substituted for corresponding atoms of old in 
expr . Example: 

subpalr[(A C);(X Y);(A BCD)] « (X B Y D) 
As with sublis , new structure is created only if 
needed, or if flq«T. e.g. if flg«WIL and there are 
no substitutions, the value is to expr . 

If i>ld ends in an atom other than NIL, the rest of 
the elements on new are substituted for that atom. 
For example, if old«(A B . C) and new»(U V X Y Z), 



To remember the order on alst . think of it as old to new, i.e. -> v 
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U is substituted for A, V for B, and (X Y Z) for 
C. Similarly, if old itself is an atom (other than 
NIL), the entire list new is substituted for it. 



Wote that subst , dsubst , Isubst , and esubst all substitute copies of the 
appropriate expression ^ whereas subpair and sublis substitute the identical 
structure (unless fla^ T), 

Value is a pointer to the last node in the list x* 
e.g. if x'^CA B C) then last[x] > (C). If 
xs(A B . C) lastCx] « (B . C). Value is NIL if x 
is not a list. 

Fast version of last that compiles open as a 5 
instruction loop, terminating on a null-check. 
Interpreted, generates an error, BAD ARGUMENT - 
FLAST, if X ends in other than NIL. 

nleftCl;n;tail] Tail is a tail of 1 or NIL. The value of nleft is 

the tail of 1 that contains n more elements than 
tall .^ e.g., if xa(A B C D E), nleft[x;2]s(D E), 
nleft[x;l;cddr[x]XB C D E). Thus nleft can be 
used to work backwards through a list. Value is 
NIL if 1 does not contain n more elements than 
tail. 



lastCx] 



flast[x] 



lastn[l;n] Value is cons[x;y] where £ is the last n elements 

of 1, and X is the initial segment, e.g. 
lastnC(A BCD E);2]8((A B C) 0 E) 



If tail is not NIL, but not a tail of 1, the result is the same as if tail 
were NIL, i.e. nleft operates by scanning 1 looking for tail , not by 
computing the lengths of 1 and tail . 
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lastn[(A B);2]«(NIL A B). 

Value is NIL if 1 is not a list containing at 
least n elements. 

Value is the tail of x beginning with the nth 
eleiaent, e.g. if ns2, value is cdr[x]» if n»3, 
cddr[x], etc. If n«l, value is x, if n«0, for 
consistency, value is consCNIL;x]. If x has fewer 
than n elements, value is NIL» e.g. 
nthr.(A B);3]-NIL, as is nth[(A . B);3] Note that 
nthHA . B);2>B. 

Fast version of nth that compiles open as a 3 
instruction loop, terminating on a null-check. 
Interpreted, generates an error, BAD ARGUNENT - 
FNTH, if x ends in other than NIL. 

Value is the length of the list x where length is 
defined as the number of cdrs required to reach a 
non-list, e.g. 

length[(A B C)] s 3 

length[(A B C . 0)] > 3 

length[A] « 0 

Fast version of length that compiles open as a 4 
instruction loop, terminating on a null-check. 
Interpreted, generates an error, BAD ARGUNENT - 
FLENGTH, if x ends in other than NIL. 

Value is the number of list words in the structure 
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X. Thus, count is like a length that goes to all 
levels. Count of a non-list is 0. 



lcliff[x;y;z] 2 "*ust be a tail of x* i*^* Sfl to the result of 

applying some number of cdrs to x. ldiff[x;y] 
gives a list of all elements in x up to ^, i.e., 
the list diff erence of x and Thus 
ldiffCx;neiDberCFOO;x]] gives all elements in x up 
to the first FOO. 

ifote that the value o/ Idiff is always new list structure unless jifklL, in 
which case the value is x itself. 

If z is not NIL the value of Idiff is effectively 
nconc[z; Idiff [x;y]], i.e. the list difference is 
added at the end of z. 

If yi is not a tail of x» generates an error, 
LDIFF: NOT A TAIL. Idiff terminates on a 
null-check. 

intersectionCx;y] Value is a list whose elements are members of both 

lists X and y. Note that intersectionCx;x] gives 
a list of all members of x without any 
duplications. 

union[x;y] Value is a (new) list consisting of all elements 

included on either of the two original lists. It 
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is more •fficient to make x be the shorter list. 

data is a list of itens to be sorted using 
comparefn . a predicate function of two argunents 
which can conpare any two items on data and return 
T if the first one belongs before the second. If 
comiparefn is NIL, alphorder is used; thus 
sortCdata] will alphabetize a list. If comparefn 
is T, car's of itens are given to alPhorder ; thus 
sort[a-list;T] will alphabetize by the car of each 
item. sortCx;ILESSP] will sort a list of 
integers . 

The value of sort is the sorted list. The sort is 
destructive and uses no extra storage. The value 
returned is eg to data but elements have been 
switched around. Interrupting with control D, E, 
or B may cause loss of data, but control H may be 
used at any time, and sort will break at a clean 
state from which t or control characters are safe. 
The algorithm has been optimized with respect to 
the number of compares. 

iiotet if compares nlQ lb] ' compttreSR[btaJ ^ then the ordering of a and b may or 
may not be preserved, " " ' 



sort[ data ; comparefn ] 
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The value of union is ^ ^^th all elements of x not in j[ cons ed on the front 
of it. Therefore, if an element appears twice in y, it will appear twice 
in union[x;y]. Also, since union[(A);(A A)] > (A A), while 
union[(A A); (A)] * (A), unio n is non -commutative. 

Sort , merge , and alphorder were written by J.W. Goodwin. 
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For example* If (FOO . FIE) appears before (FOO . FUN) in x> sortCx;T] nay or 
may not reverse the order of these two elements. Of course, the user can 
always specify a more precise comparef n » 

roergeCa;b;comparefn] a and b are lists which have previously been 

sorted using sort and comparef n . Value is a 
destructive merging of the two lists. It does not 
matter which list is longer. After merging both a 
and b are equal to the merged list. (In fact, 
cdr[a) is efl to cdr[b]) merge may be aborted after 
control H. 

alphorder[a;b] A predicate function of two arguments, for 

alphabetizing. Returns T if its arguments are in 
order, i.e. if b does not belong before a. 
Numbers come before literal atoms, and are ordered 
by magnitude (using greaterp ). Literal atoms and 
strings are ordered by comparing the (ASCII) 
character codes in their pnames. Thus 
alphorder[23;123] is T, whereas 

alphorder[A23;A123] is NIL, because the character 
code for the digit 2 is greater than the code for 
1. 



Atoms and strings are ordered before all other 
data types. If neither a nor b are atoms or 
strings, the value of alphorder is T, i.e. in 
order . 



il^otet alphorder does no unpacks . chcons . conses or nthchars . It is several 
times faster for alphabetizing than anything that can be written using 
these other functions. 
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cplists[x;y]) compares x and ^ prints their differences, 

i.e. cplists is essentially a SRCCON for list 
structures. 
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SECTION 7 
PROPERTY LISTS AND HASH LINKS 



7.1 Property Lists 



Property lists are entities associated with literal atoms, and are stored on 
cdr of the atom. Property lists are conventionally lists of the form (property 
value property value ... property value) although the user can store anything 
he wishes in cdr of a literal atom. However, the functions which manipulate 
property lists observe this convention by cycling down the property lists two 
cdrs at a time. Host of these functions also generate an error, ARG NOT ATON, 
if given an argument which is not a literal atom, i.e., they cannot be used 
directly on lists . 

The term 'property name' or 'property' is used for the property indicators 
appearing in the odd positions, and the term 'property value' or 'value of a 
property' or simply 'value' for the values appearing in the even positions . 
Sometimes the phrase 'to store on the property — ' is used, meaning to place 
the indicated information on the property list under the property name — . 

Properties are usually atoms, although no checks are made to eliminate use of 
non^atoms in an odd position. However, the property list searching functions 
all use eg . 



Property List Functions 



put[atni;prop;val] puts on the property list of atm, the property 

prop with value val. val replaces any previous 
value for the property prop on this property list. 
Generates an error, ARG NOT ATOM* if atm is not a 
literal atom. Value is val. 



addpropC atm; prop; new; fig] adds the value new to the list which is the value 

of property prop on property list of atm . If fig 
is T, new is consed onto the front of value of 
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prop , otherwise it is nconc ed on the end (nconcl). 
If atin does not have a property prop , the effect 
is the sane as put[ atm; prop ;listC new]], for 
example, if addprop[FOO; PROP; FIE] is followed by 
addpropC FOO ; PROP ; FUM ] , ge t p[ FOO ; PROP ] will 
be (FIE FUN). The value of addprop is the (new) 
property value. If atm is not a literal atom, 
generates an error, ARC NOT ATOM. 

rempropC atm; prop] removes all occurrences of the property prop (and 

its value) from the property list of atm . Value 
is prop if any were found, otherwise NIL. If atm 
is not a literal atom, generates an error, 
ARG NOT ATOM. 



changeprop[x;propl;prop2] Changes name of property prop! to prop2 on 

property list of x* (but does not affect the value 
of the property). Value is Xf unless prop! is not 
found, in which case, the value is NIL. If x is 
not a literal atom, generates an error* 
ARG NOT ATOM. 

set[x;y] Gets the item after the atom ^ on list x* If Y. 

not on the list value is NIL. For example, 
getCA B C D);B]-C. 

Notet since get terminates on a non-list, get[atomi anything J is MIL, 

Therefore, to search a property list, getp should 
be used, or get applied to cdrCatom]. 
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getp[atm;prop] gets the property value for prop from the property 

list of atro. The value of getp is NIL If atin is 
not a literal atom, or prop if not found. 

Notet the value of getp may also be HIIL, if there is an occurrence of prop but 
the corresponding property value is MIL, 

Note: Since getp searches a list two items at a 
time, the same object can be used as both a 
property name and a property value, e.g., if the 
property list of atm is (PROPi A PR0P2 B A C), 
then getp[atm;A] « C. Note however that 
get[cdrCatm];A] » PR0P2. 

getlisCx; props] searches the property list of x» and returns the 

property list as of the first property on props 
that it finds e.g., if the property list of x is 
(PROPI A PR0P3 BAG), 
getlis[x;(PR0P2 PR0P3)]«(PR0P3 B A C) 
Value is NIL if no element on props is found, x 
can also be a list itself, in which case it is 
searched as above. 

deflistCl;prop] is used to put values under the same property name 

on the property lists of several atoms. 1 is a 
list of two-element lists. The first element of 
each is a literal atom, and the second element is 
the property value for the property prop . The 
value of deflist is NIL. 

ilotet Many atoms in the system already have property lists, with properties 
used by the compiler , the break package* DWIMt etc. Be careful not to 
clobber such system properties. The value of s us props gives the complete 
list of the property names used by the system. 
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7.2 Hash Links 



The description of the hash link facility in INTEIILISP is included in the 
chapter on property lists because of the similarities in the ways the two 
features are used. A property list provides a way of associating information 
with a particular atom. A hash link is an association between any INTERLISP 
pointer (atoms, numbers, arrays, strings, lists, et al) called the hash-item, 
and any other INTERLISP pointer called the hash-value. Property lists are 
stored in cdr of the atom. Hash links are implemented by computing an address, 
called the hash-address, in a specified array, called the hash-array, and 
storing the hash-value and the hash-item into the cell with that address. The 
contents of that cell, i.e. the hash-value and hash-item, is then called the 
hash-link.^ 

Since the hash-array is obviously much smaller than the total number of 
possible hash-items,^ the hash-address computed from item may already contain a 
hash- link. If this link is from item,^ the new hash-value simply replaces the 
old hash-value. Otherwise, another hash-address (in the same hash-array) roust 
be computed, etc, until an empty cell is found, ^ or a cell containing a 
hash-link from item. 

When a hash link for item is being retrieved, the hash-address is computed 



The term hash link (unhyphenated) refers to the process of associating 
information this way, or the 'association' as an abstract concept. 

which is the total number of INTERLISP pointers, i.e., 256K. 

eg is used for comparing item with the hash-item in the cell. 

After a certain number of iterations (the exact algorithm is complicated), 
the hash-array is considered to be full, and the array is either enlarged, 
or an error is generated, as described below in the discussion of overflow. 
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using the same algorithm as that employed for making the hash link. If the 
corresponding cell is empty, there is no hash link for item. If it contains a 
hash- link from item , the hash-value is returned. Otherwise, another 
hash-address must be computed* and so forth. ^ 

Note that more than one hash link can be associated with a given hash-item by 
using more than one hash-array. 

Hash Link Functions 

In the description of the functions below, the argument array has one of three 
forms: (1) NIL, in which case the hash-array provided by the system, 
syshasharray , is used;^ (2) a hash-array created by the function harray . or 
created from an ordinary array using clrhash as described below; or (3) a list 
car of which is a hash-array. The latter form is used for specifying what is 
to be done on overflow, as described below. 

harray[n] creates a hash-array of size n, equivalent to 

clrhashC array[ n ] ] . 

clrhash[ array] sets all elements of array to 0 and sets left half 

of first word of header to -I. Value is array . 

puthashCitem;val;array] puts into array a hash-link from item to val. 



For reasonable operation, the hash array should be ten to twenty percent 
larger than the maximum number of hash links to be made to it. 



syshasharray is not used by the system, it is provided solely for the 
user's benefit. It is initially 512 words large, and is automatically 
enlarged by 50X whenever it is *full'. See page 7.7. 



Replaces previous link from same item, if any. If 
valsNIL any old link is removed, (hence a 
hash-value of NIL is not allowed). Value is val. 



gethash[itero;array] 



finds hash-link from item in array , and returns 
the hash-value. Value is NIL if no link exists. 
gethash compiles open. 



rehashC oldar ; newar ] 



hashes all items and values in oldar into newar . 
The two arrays do not have to be (and usually 
aren't) the same size. Value is newar. 



maphashC array ;maphfn] 



maphfn is a function of two arguments. For each 
hash-link in array , maphfn will be applied to the 
hash-value and hash-item, e.g. 

maphash[a;(LAMBOA(X Y) (ANO(LISTP Y) (PRINT X)))] 
will print the hash-value for all hash-links from 
lists. The value of maphash is array . 



drophashC arrayname ] 



Nlajnbda-nospread that prints on the primary output 
file a load able form which will restore what is in 
thei hash-array specified by arrayname , e.g. 
(E (DMPHASH SYSHASHARRAY)) as a prettydef command 
will dump the system hash-array. 



Notet all identities except atoms and small integers are lost by dumping and 
loading because read will create new structure for each item. Thus if 
two lists contain an e£ substructure, when they are dumped and loaded 
back in, the corresponding substructures while equal are no longer en/ 



circlprint and circlmaker (Section 21) provide a way of dumping and 
reloading structures containing e£ substructures so that these identities 
are preserved. 
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Hash Overflow 



By using an array argument of a special form, the user can provide for 
automatic enlargement of a hash-array when it overflows, i.e., is full and an 
attempt is made to store a hash link into it. The array argument is either of 
the form (hash-array . n), n a positive integer; or (hash-array . f), f a 
floating point number; or (hash-array). In the first case, a new hash-array is 
created with n more cells than the current hash-array. In the second case, the 
new hash array will be f times the size of the current hash-array. The third 
case, (hash-array), is equivalent to (hash-array . 1.5). In each case, the old 
hash-array is rplaca ed into the dotted pair, and the computation continues. 

If a hash-array overflows, and the array argument used was not one of these 
three forms, the error HASH TABLE FULL is generated, which will either cause a 
break or unwind to the last errorset , as per treatment of errors described in 

Section 16. 

The system hash array, syshasharray , is automatically enlarged by 1.5 when it 
is full. 
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SECTION 8 
FUNCTION DEFINITION AND EVALUATION 



General Comments 

A function definition in INTERLISP is stored in a special cell called the 
function definition cell, which is associated with each literal atom. This 
cell is directly accessible via the two functions putd , which puts a definition 
in the cell, and getd which get s the definition from the cell. In addition, 
the function fntyp returns the function type, i.e., EXPR, EXPR* . . . FSUBR* as 
described in Section 4. Exprp , ccodep . and subrp are true if the function is 
an expr, compiled function, or subr respectively; argtype returns 
0, 1, 2, or 3, depending on whether the function is a spread or nospread (i.e., 
its fntyp ends in or evaluate or no-evaluate (i.e., its fntyp begins with F 
or CF); argllst returns the list of arguments; and nargs returns the number of 
arguments, fntyp , exprp , ccodep , subrp , argtype , argllst , and nargs can be 
given either a literal atom, in which case they obtain the function definition 
from the atom's definition cell, or a function definition itself. 

Subrs 

Because subrs,'' are called in a special way, their definitions are stored 



Basic functions, handcoded in machine language, e.g. cons , car , cond . The 
terms subr includes spread/nospread, sval/noeval functions, i.e. the four 
fntyp 's SUBR. FSUBR, SUBR«, and FSUBR*. 
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differently than those of compiled or interpreted functions. In the right half 
of the definition cell is the address of the first instruction of the subr,, and 
in the left half its argtype t 0, 1, Z, or 3. getd of a subr returns a dotted 
pair of argtype and address. Note that this is not the same word as appears in 
the definition cell, but a new cons ; i.e., each getd of a subr performs a cons . 
Similarly, putd of a definition of the form (number . address), where number & 
0, 1, 2, or 3, and address is in the appropriate range, stores the definition 
as a subr, i.e., takes the cons apart and stores car in the left half of the 
definition cell and cdr in the right half. 

Validity of Definitions 

Although the function definition cell is intended for function definitions, 
putd and getd do not make thorough checks on the validity of definitions that 
"look like" exprs, compiled code, or subrs. Thus if putd is given an array 
pointer, it treats it as compiled code, and simply stores the array pointer in 
the definition cell, getd will then return the array pointer. Similarly, a 
call to that function will simply transfer to what would normally be the entry 
point for the function, and produce random results if the array were not 
compiled function. 

Similarly, if putd is given a dotted pair of the form (number . address) where 
number is 0, 1, 2, or 3, and address falls in the subr range, putd assumes it 
is a subr and stores it away as described earlier, getd would then return cons 
of the left and right half, i.e., a dotted pair equal (but not eg) to the 
expression originally given putd . Similarly, a call to this function would 
transfer to the corresponding address. 

Finally, if putd is given any other list, it simply stores It away. A call to 
this function would then go through the Interpreter as described in the 
appendix. 
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Note that putd does not actually check to see if the s-expression is valid 
definition, i.e., begins with LAMBDA or NLAMBOA. Similarly, exprp is true if a 
definition is a list and not of the form (number . address), number b 
0, 1, 2, or 3 and address a subr address; subrp is true if it is of this form. 
argli&t and nargs work correspondingly. 

Only fntyp and argtype check function definitions further than that described 
above: both argtype and fntyp return NIL when exprp is true but car of the 
definition is not LAMBDA or NLAMBDA.'^ In other words, if the user uses putd to 
put (A B C) in a function definition cell, getd will return this value, the 
editor and prettyprint will both treat it as a definition, exprp will return T, 
ccodep and subrp NIL, arglist B, and nargs 1. 

getd[x] get s the function definition of x. Value is the 

definition.^ Value is NIL if x is not a literal 
atom, or has no definition. 



fgetd[x] fast version of getd that compiles open as 

car[vag[addl[loc[x3]]]. Interpreted, generates an 
error* BAD ARGUMENT - F6ETD, if x is not a literal 
atom.^ 



These functions have different value on LAMBDAS and NLAMBDAs and hence must 
check. The compiler and interpreter also take different actions for 
LAMBDAS and NLAMBDAs, and therefore generate errors if the definition is 
neither. 

Note that getd of a subr performs a cons, as described on page 8.2. See 
footnote on fgetd below. 



Fgotd is intended primarily to check whether a function ha^ a definition, 

rather than to obtain the definition. Therefore, for subrs, fgetd returns 

Just the address of the function definition, not the dotted pair returned 
getd , page 8.2, thereby saving the cons . 
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putd[x;y] put s the definition ^ into x'^ function cell. 

Value is Generates an error, ILLEGAL ARG - 
PUTD, if X is not a literal atom, or is a 
string, number, or literal atom other than NIL. 

putdq[x;y] n lambda version of putd ; both arguments are 

considered quoted. Value is x* 

movd[from;to;copyflg] Moves the definition of from to to, i.e., 

redefines to. If copyf Ig gJ, a copy of the 
definition of from is used. copyflg eT is only 
meaningful for exprs, although movd works for 
compiled functions and subrs as well. The value 
of movd is to. 

Notet fntyp , subrp , ccodep , expr p, argtupe . nargs , and arglist all can be given 
either the name of a function, or a definition. 

fntyp[fn] Value is NIL if fn is not a function definition or 

the name of a defined function. Otherwise fntyp 
returns one of the following as defined in the 
section on function types: 



EXPR 


CEXPR 


SUBR 


FEXPR 


CFEXPR 


FSUBR 


EXPR* 


CEXPR* 


SUBR* 


FEXPR* 


CFEXPR* 


FSUBR* 



The prefix F indicates unevaluated arguments, the 
prefix C indicates compiled code; and the suffix * 
indicates an indefinite number of arguments. 
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fntyp returns FUNAR6 if fn is a funarg expression. 
See Section 11. 

is true if and only if fntyp[fn] is either SUBR, 
FSUBR, SUBR", or FSUBR", i.e., the third column of 
fntyp *s. 

is true if and only if fntyp[fn] is either CEXPR, 
CFEXPR, CEXPR", or CFEXPR*, i.e., second column of 
fntyp 's. 

is true if fntypCfn] is either EXPR, FEXPR, EXPR*. 
or FEXPR*, i.e., first column of fntyp's. 
However, exprp[fn] is also true if fn is (has) a 
list definition that is not a SU6R, but does not 
begin with either LAMBDA or NLAMBOA. In other 
words, exprp is not quite as selective as fntyp . 

fn is the name of a function or its definition. 
The value of argtype is the argtype of fn, i.e., 
0, 1, 2, or 3, or NIL if fn is not a function. 
The interpretation of the argtype is: 

0 eval/spread function 

(EXPR, CEXPR, SUBR) 

1 no-eval/spread functions 

(FEXPR, CFEXPR, FSUBR) 

2 eval/nospread functions 

(EXPR«, CEXPR«, SUBR«) 

3 no-eval/nospread functions 

(FEXPR*, CFEXPR*, FSUBR*) 

i>«*> argtype corresponds to the rows of f n typs . 
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nargs[fn] value Is the number of arguments of fn» or NIL if 

fn is not a function.^ naras uses exprp . not 
fntyp. so that nargs[(A (B C) 0)]«2. Note that if 
fn is a SUBR or FSUBR, nargs « 3, regardless of 
the number of arguments logically needed/used by 
the routine. If fn is a nospread function, 
nargs » 1. 

arglist[fn] value is the 'argument list* for fn. Note that 

the 'argument list* is an atom for nospread 
functions. Since NIL is a possible value for 
arglist . an error is generated, 
ARGS NOT AVAILABLE, if fn is not a function.^ 

If fn is a SUBR or FSUBR, the value of arglist is (U V W), if a SUBR* or 
FSUBR*, the value is U. This is merely a 'feature' of arglist , subrs do not 
actually store the names U, V, or W on the stack. However, if the user breaks 
or traces a SUBR (Section 15), these will be the argument names used when an 
equivalent EXPR definition is constructed. 

define[x] The argument of define is a list. Each element of 

the list is itself a list either of the form (name 
definition) or (name arguments ...). In the 
second case, following 'arguments' is the body of 
the definition. As an example, consider the 
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i.e., if exprp . ccodep . and subrp are all NIL. 

If fn is a compiled function, the argument list is constructed, i.e. each 
call to arglist requires making a new list. For interpreted functions, the 
argument list is simply cadr of getd . 
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following two equivalent expressions for defining 
the function null . 

1) (NULL (LAMBDA (X) (EQ X NIL)}) 

2) (NULL (X) (EQ X NIL)) 

def ine will generate an error on encountering an atom where a defining list is 
expected. If dfnflg aNIL, an attempt to redefine a function fn will cause 
define to print the message (fn REDEFINED) and to save the old definition of fn 
usii^O savedef before redefining it. If dfnf Ig sT, the function is simply 
redefined. If dfnf Ig sPROP or ALLPROP» the new definition is stored on the 
property list under the property EXPR. (ALLPROP affects the operation of rpaqq 
and rpaq , section 5). dfnflg is initially NIL. 

dfnf Ig is reset by load to enable various ways of handling the defining of 
functions and setting of variables when loading a file. For most applications, 
the user will not reset dfnflg directly himself. 

^ote: define will operate correctly if the function is already defined and 
bro/ien , advised * or broken-in , 

n lambda nospread version of define , i.e., takes an 
indefinite number of arguments which are not 
evaluated. Each x^ must be a list, of the form 
described in define , def ineq calls define , so 
dfnflg affects its operation the same as define . 

savedef [fn] Saves the definition of fn on its property list 

under property EXPR, CODE, or SUBR depending on 
fntyp . Value is the property name used. If 
getdCfn] is non-NIL, but fntyp[fn!| is NIL, saves 
on property name LIST. This situation can arise 



def ineq[X| ;x^; . . . ;x^] 
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when a function is redefined which was originally 
defined with LAMBDA misspelled or omitted. 

If fn is a list, savedef operates on each function 
in the list, and its value is a list of the 
individual values . 

unsavedefCfn;prop] Restores the definition of fn from its property 

list under property prop (see savedef above). 
Value is prop . If nothing saved under prop , and 
fn is defined, returns (prop NOT FOUND), otherwise 
generates an error, NOT A FUNCTION. 

If prop is not given, i.e. NIL, unsavedef looks 
under EXPR, CODE, and SUBR, in that order. The 
value of unsavedef is the property name, or if 
nothing is found and fn is a function, the value 
is (NOTHING FOUND); otherwise generates an error, 
NOT A FUNCTION. 

If dfnflg sNIL. the current definition of fn, if 
any,, is saved using savedef . Thus one can use 
unsavedef to switch back and forth between two 
definitions of the same function, keeping one on 
its property list and the other in the function 
definition cell. 

If fn is a list, unsavedef operates on each 
function of the list, and its value is a list of 
the individual values. 
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eval[x] eval evaluates the expression x and returns this 

value i.e. eval provides a way of calling the 
interpreter. Note that eval is itself a lambda 
type function, so its argument is the first 
evaluated, e.g.. 



«-SET(FOO (AODl 3)) 
(ADDl 3) 
♦-(EVAL FOO) 
4 

«-EVAL(FOO) or (EVAL (QUOTE FOO)} 
(ADDl 3} 



e[x] n lambda nospread version of eval . Thus it 

eliminates the extra pair of parentheses for the 
list of arguments for eval . i.e., e x is 
equivalent to eval[x]. Note however that in 
INTERLISP, the user can type Just x to get x 
evaluated. (See Section 3.) 

applyCfn;args] apply applies the function fn to the arguments 

arqs . The individual elements of args are not 
evaluated by apply , fn is simply called with args 
as its argument list. Thus for the purposes of 
apply , nlambda 's and lambda's are treated the 
same. However like eval , apply is a lambda 
function so its arguments are evaluated before it 
is called e.g.. 
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eval is a subr so that the 'name' x does not actually appear on the stack. 

Note that fn may still explicitly evaluate one or more of its arguments 
itself, as in the case of setq . Thus 

(APPLY (QUOTE SETQ) (QUOTE (FOO (ADDl 3)))) will set FOO to 4, whereas 
(APPLY (QUOTE SET) (QUOTE (FOO (ADDl 3)))) will set FOO to the expression 
(AODl 3). 
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-SET(F00l 3) 
3 

-SEKFOOZ 4) 
4 

«-(APPLY (QUOTE IPLUS) (LIST FOOl F002] 
7 



Here, fool and foo2 were evaluated when the second 



argument to apply was evaluated. Compare with: 



*-SET(F001 (ADDl 2)) 
(ADDl 2) 

«-SET(F002 (SUBl 5)) 
(SUBl 5) 

^(APPLY (QUOTE IPLUS) (LIST FOOl F002] 

NON-NUMERIC ARG 
(ADDl 2) 



apply*[fn;argj; . . . ;arOjj] equivalent to apply[fn;listCarg^; . . . ;arg^]] For 

example, if fn is the name of a functional 
argument to be applied to x and y^, one can write 
(APPLY* FN X Y). which is equivalent to 
(APPLY FN (LIST X Y)). Note that (FN X Y) 
specifies a call to the function FN itself, and 
will cause an error if FN is not defined. (See 
Section 16.) FN will not be evaluated. 



evalaCx;a] Simulates a-list evaluation as in LISP 1.5. x is a 

form, a is a list of dotted pairs of variable name 
and value, a is 'spread' on the stack, and then x 
is evaluated, i.e., any variables appearing free 
in X, that also appears as car of an element of a 
will be given the value in the cdr of that 
element. 

rpt[rptn;rptf ] Evaluates the expression rptf rptn times. At any 

point, rptn is the number of evaluations yet to 



8.10 



take place. Returns the value of the last 
evaluation. If rptn < 0, rptf is not evaluated, 
and the value of rgt is NIL. 

Notet rpt is a lambda Junction* so both its arguments are evaluated before rpt 
is called. For most applications t the user will probably want to use 

rptq[rptn;rptf ] n lambda version of rpt; rptn is evaluated, rptf is 

not, e.g. (ftPTQ 10 (READ)) will perform ten calls 
read , rptq compiles open. 

arg[var;ni] Used to access the individual arguments of a 

lambda nospread function. ar£ is an n lambda 
function used like set yar is the name of the 
atomic argument list to a lambda-nospread 
function, and is not evaluated; m is the number of 
the desired argument, and is evaluated. For 
example, consider the following definition of 
iplus in terms of plus . 

[LAMBDA X 
(PROG ((M 0) 
(N 0)) 
LP (COND 

((EQ N X) 
(RETURN M))) 
(SETQ N (ADDl N)} 
[SETQ M (PLUS N (ARG X N))) 
(GO LP] 



The value of arg is undefined for m less than or 

o 

equal to 0 or greater than the value of var .^ 
Lower numbered arguments appear earlier in the 
form, e.g. for (IPLUS ABC), 



For lambda nospread functions, the lambda variable is bound to the number 
of arguments actually given to the function. See Section 4. 
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arg[X;l>the value of A, 
arg[X;2]Bthe value of B, and 
arg[X;3]sthe value of C. 

Note that the lambda variable should never be 
reset. However, Individual arguments can be reset 
using setarg described below. 

set s to X the mth arg ument for the lambda nospread 
function whose argument list is var . var is 
considered quoted, m and x are evaluated; e.g. in 
the previous example. (SETARG X (AODl N)(MINUS M)} 
would be an example of the correct forn for 
setarg . 
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FNTYPCX] 8.1.3-7 
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nospread 8.1 
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(NOT FOUND) 8.8 
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PROP[X;Y] 8.7 
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SECTION 9 
THE INTERLISP EDITOR 



The INTERLISP editor allows rapid, convenient nodification of list structures. 
Most often it is used to edit function definitions, (often while the function 
itself is running) via the function edltf . e.g., EDITF(FOO). However, the 
editor can also be used to edit the value of a variable, via editv, to edit a 
property list, via editp . or to edit an arbitrary expression, via edite. It is 
an important feature which allows good on-line interaction in the INTERLISP 
system. 

This chapter begins with a lengthy introduction intended for the new user. The 
reference portion begins on page 9. IS. 

9.1 Introduction 

Let us introduce some of the basic editor commands, and give a flavor for the 
editor's language structure by guiding the reader through a hypothetical 
editing session. Suppose we are editing the following incorrect definition of 

append ! 



The editor was written by and is the responsibility of W. Teltelman. 



[LAMBDA (X) 
Y 

(COND 
((NUL X) 
Z) 

(T (CONS (CAR]i 

(APPEND (CDR X Y] 



We call the editor via the function editf ; 



-EOITF(APPEND) 
EDIT 



The editor responds by typing EDIT followed by which is the editor's prompt 
character, i.e., it signifies that the editor is ready to accept comnands.^ 



At any given moment, the editor's attention is centered on some substructure of 
the expression being edited. This substructure is called the current 
expression, and it is what the user sees when he gives the editor the command 
P, for print. Initially, the current expression is the top level one, i.e., 
the entire expression being edited. Thus: 

«P 

(LAMBDA (X) Y (COND & &)) 
* 

Note that the editor prints the current expression as though printlevel were 
set to 2, i.e., sublists of subllsts are printed as ft. The command 7 will 
print the current expression as though printlevel were 1000. 

*? 

(LAMBDA (X) Y (COND ((NUL X) Z) (T (CONS (CAR) (APPEND (CDR X Y)))))) 
and the command PP will prettyprint the current expression. 



In other words, all lines beginning with * were typed by the user, the rest 
by the editor. 
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A positive integer is interpreted by the editor as a connand to descend into 
the correspondingly numbered elenent of the current expression. Thus: 



»2 
«P 
(X) 



A negative integer has a similar effect, but counting begins from the end of 
the current expression and proceeds backward, i.e., *1 refers to the last 
element in the current expression, -2 the next to the last, etc. For either 
positive integer or negative integer, if there is no such element, an error 
occurs,^ the editor types the faulty conmand followed by a ?, and then another 
*. The current expression is never changed when a commend causes an error. 
Thus: 

«P 

(X) 

«2 

2 ? 

*1 

*P 

X 

« 



A phrase of the form 'the current expression is changed* or *the current 
expression becomes* refers to a shift in the editor* s attention , not to a 
modification of the structure being edited* 



When the user changes the current expression by descending into it, the old 
current expression is not lost. Instead, the editor actually operates by 



'Editor errors' are not of the flavor described in Section 16, i.e., they 
never cause breaks or even go through the error machinery but are direct 
calls to error! indicating that a command is in some way faulty. What 
happens next depends on the context in which the command was being 
executed. For example, there are conditional commands which branch on 
errors. In most situations, though, an error will cause the editor to type 
the faulty command followed by a 7 and wait for more input. Note that 
typing control-E while a command is being executed aborts the conmand 
exactly as though it had caused an error. 
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maintaining a chain of expressions leading to the current one. The current 
expression is simply the last link in the chain. Descending adds the indicated 
subexpression onto the end of the chain, thereby making it be the current 
expression. The command 0 is used to ascend the chain; it removes the last 
link of the chain, thereby making the previous link be the current expression. 
Thus: 

«P 

X 

«0 P 
(X) 

*0 -1 P 

(COND (& Z) (T &)) 

Note the use of several commands on a single line in the previous output. The 
editor operates in a line buffered mode, the same as evalqt . Thus no command 
is actually seen by the editor, or executed, until the line is terminated, 
either by a carriage return, or a matching right parenthesis. The user can 
thus use control-A and control-Q for line*editing edit commands, the same as he 
does for inputs to evalqt . 

In our editing session, we will make the following corrections to append ; 
delete Y from where it appears, add Y to the end of the argument list,^ change 
NUL to NULL, change Z to Y, add Z after CAR, and insert a right parenthesis 
following CDR X. 

First we will delete Y. By now we have forgotten where we are in the function 
definition, but we want to be at the "top" so we use the command t, which 
ascends through the entire chain of expressions to the top level expression. 



These two operations could be though of as one operation, i.e., MOVE Y from 
its current position to a new position, and in fact there is a MOVE command 
in the editor. However, for the purposes of this introduction, we will 
confine ourselves to the simpler edit commands. 
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which then becomes the current expression, l.iB,» t removes ell links except the 
first one. 

«t P 

(LANBOA (X) Y (COND & ft)) 
* 

Note that if we are already at the top, t has no effect, i.e., it is a NOP. 
However, 0 would generate an error. In other words, t means "go to the top," 
while 0 means "ascend one link.* 

The basic structure modification commands in the editor are: 

(n) n > 1 deletes the corresponding 

element from the current expression. 

(n e^ ... e^) n,m > 1 replaces the nth element in the current 

expression with 

®1 • • • ®m* 

n,m > 1 inserts e^ ... e^^ before the nth element 
in the current expression. 

Thus: 

*P 

(LAMBDA (X) Y (COND & &)) 
*(3) 

*(2 (X Y)) 
«p 

(LAMBDA (X Y) (COND & &)) 

All structure modification done by the editor is destructive* i.e.. tAe editor 
uses r place and rplacd to physically change the structure it mas given* 

Note that all three of the above commands perform their operation with respect 



(m oj ... ej 
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to the nth element from the front of the current expression; the sign of n is 
used to specify whether the operation is replacement or insertion. Thus» there 
is no way to specify deletion or replacement of the nth element from the end of 
the current expression, or insertion before the nth element from the end 
without counting out that element's position from the front of the list. 
Similarly, because we cannot specify insertion after a particular element, we 
cannot attach something at the end of the current expression using the above 
commands. Instead, we use the command N (for nconc). Thus we could have 
performed the above changes instead by: 



*P 

(LAMBDA (X) Y (COMO & &)) 
M3) 

«2 (N Y) 
*P 

(X Y) 
«t P 

*( LAMBDA (X Y) (COND & &)) 
* 



Now we are ready to change NUL to NULL. Rather than specify the sequence of 
descent commands necessary to reach NUL, and then replace it with NULL, e.g., 3 
2 1(1 NULL), we will use F, the find command, to find NUL: 



*P 

(LAMBDA (X Y) (COND & &)) 

*F NUL 

*P 

(NUL X) 
«(1 NULL) 
«0 P 

((NULL X) Z) 
* 



Note that F is special in that it corresponds to tioo inputs. In other words, F 
says to the editor, "treat your next command as an expression to be searched 
for." The search is carried out in printout order in the current expression. 
If the target expression is not found there, F automatically ascends and 
searches those portions of the higher expressions that would appear after (in a 
printout) the current expression. If the search is successful, the new current 
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expression will be the structure where the expression was found, ^ and the chain 
will be the same as one resulting fron the appropriate sequence of ascent and 
descent commands. If the search is not successful, an error occurs, and 
neither the current expression nor the chain is changed:^ 

«P 

((NULL X) Z) 
«F CONO P 

COND ? 
«P 

*((NULL X) Z) 



Here the search failed to find a cond following the current expression, 
although of course a cond does appear earlier in the structure. This last 
example illustrates another facet of the error recovery mechanism: to avoid 
further confusion when an error occurs, all commands on the line beyond the one 
which caused the error (and all conmands that may have been typed ahead while 
the editor was computing) are forgotten. 

We could also have used the R command (for replace) to change NUL to NULL. A 
command of the form (R e| e^) will replace all occurrences of e| in the current 
expression by e^. There must be at least one such occurrence or the R command 
will generate an error. Let us use the R connand to change all Z*s (even 
though there is only one) in append to Y: 



If the search is for an atom, e.g., F NUL, the current expression will be 
the structure Containing the atom. 



6 



7 



F is never a NOP, i.e., if successful, the current expression after the 
search will never be the same as the current expression before the search. 
Thus F expr repeated without intervening commands that change the edit 
chain can be used to find successive instances of expr . 

i.e. the input buffer is cleared (and saved) (see clearbuf , Section 14). 
It can be restored, and the type-ahead recovered via the command SBUFS 
(alt-mode BUFS), described in Section 22. 
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«t (R Z Y) 
«F Z 

Z ? 
*PP 

[LAMBDA (X Y) 
(COND 

((NULL X) 
Y) 

(T (CONS (CAR) 

(APPEND (CDR X Y] 

« 



The next task is to change (CAR) to (CAR X). We could do this by 
(R (CAR) (CAR X)), or by: 



«F CAR 
«(N X) 
«P 

(CAR X) 



The expression we now want to change is the next expression after the current 
expression, i.e., we are currently looking at (CAR X) in (CONS (CAR X) (APPEND 
(CDR X Y))). We could get to the append expression by typing 0 and then 3 or 
-1, or we can use the command NX, which does both operations: 



«P 

(CAR X) 
«NX P 

(APPEND (CDR X Y)) 
* 



Finally, to change (APPEND (CDR X Y)) to (APPEND (CDR X) Y), we could perform 
(2 (CDR X) Y), or (2 (CDR X)) and (N Y), or 2 and (3), deleting the Y, and then 
0 (N Y). However, if Y were a complex expression, we would not want to have to 
retype it. Instead, we could use a command which effectively inserts and/or 
removes left and right parentheses. There are six of these commands: 
BI,BO,LI,LO,RI, and RO, for both in, both out, left in, left out, right in, and 
right out. Of course, we will always have the same number of left parentheses 
as right parentheses, because the parentheses are just a notational guide to 
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structure that is provided by our print program. Thus, left in, left out, 
right in, and right out actually do not insert or remove Just one parenthesis, 
but this is very suggestive of what actually happens. 

In this case, we would like a right parenthesis to appear following X in (CDR X 
Y). Therefore, we use the coomiand (RI 2 2), which means insert a right 
parentheses after the second element in the second element (of the current 
expression): 

*P 

(APPEND (CDR X Y)) 

*(RI 2 2) 

«P 

(APPEND (CDR X) Y) 
« 

We have now finished our editing, and can exit from the editor, to test append , 
or we could test it while still inside of the editor, by using the E command: 

*E APPENO((A B) (C 0 E)) 
(A B C D E) 

The E command causes the next input to be given to evalqt . If there is another 
input following it, as in the above example, the first will be applied ( apply ) 
to the second. Otherwise, the input is evaluated (eval). 

We prettyprint append , and leave the editor. 



Herein lies one of the principal advantages of a LISP oriented editor over 
a text editor: unbalanced parentheses errors are not possible. 
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[LAMBDA (X Y) 
(COND 

((NULL X) 
Y) 

(T (CONS (CAR X) 



9.2 Commands for the Mew User 

As mentioned earlier, the INTERIISP manual is intended primarily as a reference 
manual, and the remainder of this chapter is organized and presented 
accordingly. While the commands introduced in the previous scenario constitute 
a complete set, i.e., the user could perform any and all editing operations 
using Just those commands, there are many situations in which knowing the right 
command(s) can save the user considerable effort. We include here as part of 
the introduction a list of those commands which are not only frequently 
applicable but also easy to use. They are not presented in any particular 
order, and are all discussed in detail in the reference portion of the chapter. 

UNDO undoes the last modification to the structure 



being edited, e.g., if the user deletes the wrong 
element, UNDO will restore it. The availability 
of UNDO should give the user confidence to 
experiment with any and all editing commands, no 
matter how complex, because he can always reverse 
the effect of the command. 



(APPEND (CDR X) Y] 



*0K 

APPEND 



BK 



like NX, except makes the expression immediately 



before the current expression become current. 



BF 



backwards find . 



Like 



except 



searches 



backwards, i.e 



• » 



in inverse print order. 
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\ Restores the current expression to the expression 

before the last "big Jump", e.g., a find comnand, 
an t, or another \. For example, if the user 
types F CONO, and then F CAR, \ would take him 
back to the CONO. Another \ would take him back to 
the CAR. 

\P like \ except it restores the edit chain to its 

state as of the last print, either by P, 7, or PP. 
If the edit chain has not been changed since the 
last print, \P restores it to its state as of the 
printing before that one, i.e., two chains are 
always saved. 

Thus if the user types P followed by 3 2 1 P, \P will take him back to the 
first P, i.e., would be equivalent to 0 0 0. Another \P would then take him 
back to the second P. Thus the user can use \P to flip back and forth between 
two current expressions. 

The search expression given to the F or BF command 
need not be a literal S-expression. Instead, it 
can be a pattern. The symbol & can be used 
anywhere within this pattern to match with any 
single element of a list, and -- can be used to 
match with any segment of a list. Thus, in the 
incorrctct definition of append used earlier, 
F (NUL &) could have been used to find (NUL X), 
and F (CDR — ) or F (CDR & &), but not F (CDR &), 
to find (COR X Y). 

Note that ft and — can be nested arbitrarily deeply in the pattern. For 
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example, if there are many places where the variable X is set, F SETQ may not 
find the desired expression, nor may F (SETQ X &). It may be necessary to use 
F (SETQ X (LIST --)). However, the usual technique in such a case is to pick 
out a unique atom which occurs prior to the desired expression, and perform two 
F commands. This "homing in" process seems to be more convenient than ultra- 
precise specification of the pattern. 

S (alt-mode) $ Is equivalent to at the character level, e.g. 

VERS will match with VERYLONGATON, as will SATOM, 
SLONGS, (but not SL0N6) and SVSNSMS. S can be 
nested inside of a pattern, e.g., 

F CSETQ VERS (CONS — )). 

If the search is successful, the editor will print 

s followed by the atom which matched with the S- 

atom, e.g., 

«F (SETQ VERS &) 
^VERYLONGATON 

Frequently the user will want to replace the entire current expression, or 
insert something before it. In order to do this using a command of the form (n 

^1 *'* ^m^ ^'^ ®1 '** ®m^' ^'^^ ^^^^ must be above the current expression. 
In other words, he would have to perform a 0 followed by a command with the 
appropriate number. However, if he has reached the current expression via an F 
command, he may not know what that number is. In this case, the user would 
like a command whose effect would be to modify the edit chain so that the 
current expression became the first element in a new, higher current 
expression. Then he could perform the desired operation via (1 e. ... e.) or 
(-1 e^ ... e^). UP is provided for this purpose. 
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UP after UP operates, the old current expression is 

the first element of the new current expression. 
Note that if the current expression happens to be 
the first element in the next higher expression, 
then UP is exactly the sane as 0. Otherwise, UP 
modifies thie edit chain so that the new current 
expression is a tail^ of the next higher 
expression: 

«F APPEND P 
(APPEND (CDR X) Y) 
*UP P 

... (APPEND & Y)) 
«0 P 

(CONS (CAR X) (APPEND & Y)) 

« ■ ■' 

The ... is used by the editor to indicate that the 
current expression is a tail of the next higher 
expression as opposed to being an element (i.e., a 
member) of the next higher expression. Note: if 
the current expression is alreadu a tail, UP has 
no effect. 

(B e^ ... inserts e^ ... before the current expression, 

i.e., does an UP and then a -1. 

(A e| ... e^) inserts e^ ... after the current expression, 

i.e., does an UP and then either a (-2 e| ... e^^) 
or an (N e^ ... e^^), if the current expression is 
the last one in the next higher expression. 



Throughout this chapter 'tail' means 'proper tail' (see Section 8). 
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replaces current expression by e^ 
does an UP and then a (1 e| ... e^g). 



e^, i.e 
n 



• $ 



DELETE 



deletes current expression; equivalent to (:). 



Earlier, we introduced the RI command in the append example. The rest of the 
comroands in this family: BI, B0„ LI, LO, and RO, perform similar functions and 
are useful in certain situations. In addition, the commands NBO and XTR can be 
used to combine the effects of several comroands of the BI-BO family. MBO is 
used to embed the current expression in a larger expression. For example, if 
the current expression is (PRINT bigexpression), and the user wants to replace 
it by (COND (FLG (PRINT bigexpression))), he could accomplish this by (LI 1), 
(-1 FLG), (LI 1), and (-1 COND),, or by a single MBD command, page 9.47. 

XTR is used to extract an expression from the current expression. For example, 
extracting the PRINT expression from the above CONO could be accomplished by 
(1), (LO 1), (1), and (LO 1) or by a single XTR command. The new user is 
encouraged to include XTR and HBO in his repertoire as soon as he is familiar 
with the more basic commands. 

This ends the introductory material. 
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9.3 Attention Changing Commands 



Commands to the editor fall into three classes: commands that change the 
current expression (i.e., change the edit chain) thereby "shifting the editor's 
attention," commands that modify the structure being edited, and miscellaneous 
commands, e.g., exiting from the editor, printing* evaluating expressions, etc. 

Within the context of commands that shift the editor's attention, we can 
distinguish among (1) those commands whose operation depends only on the 
structure of the edit chain, e.g., 0, UP, NX; (2) those which depend on the 
contents of the structure, i.e., commands that search; and (3) those commands 
which simply restore the edit chain to some previous state, e.g., \, \P« (i) 
and (2) can also be thought of as local, small steps versus open ended, big 
Jumps. Commands of type (1) are discussed on page 9.15-21, type (2) on page 
9.21-34, and type (3) on page 9.34-36. 

9.3.1 Local Attention-Changing Commands 

UP (1) If a P command would cause the editor to type 

... before typing the current expression, i.e. the 
current expression is a tail of the next higher 
expression, UP has no effect; otherwise 
(2) UP modifies the edit chain so that the old 
current expression (i.e., the one at the time UP 
was called) is the first element in the new 
current. xpre.si.n.'« 



If the current expression is the first element in the next higher 
expression UP simply does a 0. Otherwise UP adds the corresponding tall to 
the edit chain. 
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Examples: The current expression in each case is 
(COND ((NULL X) (RETURN Y))). 



1. "l P 
COND 
*UP P 

(COND (& &)) 

2. «-l P 

((NULL X) (RETURN Y)) 
*UP P 

... ((NULL X]i (RETURN Y)) 
•UP P 

... ((NULL X) (RETURN Y))) 

3. «F NULL P 
(NULL X) 
*UP P 

((NULL X) (RETURN Y)) 
*UP P 

... ((NULL X} (RETURN Y))) 



The execution of UP is straightforward, except in those cases where the current 
expression appears more than once in the next higher expression. For example » 
if the current expression is (A NIL B NIL C NIL) and the user performs 4 
followed by UP, the current expression should then be ... NIL C NIL). UP can 
determine which tail is the correct one because the commands that descend save 
the last tail on an internal editor variable, lastail. Thus after the 4 
command is executed, lastail is (NIL C NIL). When UP is called, it first 
determines if the current expression is a tail of the next higher expression. 
If it is, UP is finished. Otherwise, UP computes 

merob[ current-expression ;next-higher-expres8ion] to obtain a tail beginning with 
the current express ion. If there are no other instances of the current 
expression in the next higher expression, this tail is the correct one. 



The current expression should always be either a tail or an element of the 
next higher expression. If it is neither, for example the user has 
directly (and incorrectly) manipulated the edit chain, UP generates an 
error. 
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otherwise UP uses lastail to select the correct tall. 

n (n > 1) adds the nth element of the current expression to 

the front of the edit chain, thereby making it be 
the new current expression. Sets lastail for use 
by UP. Generates an error if the current 
expression is not a list that contains at least n 
elements. 



-n (n > 1) adds the nth element from the end of the current 

expression to the front of the edit chain, thereby 
making it be the new current expression. Sets 
lastail for use by UP. Generates an error if the 
current expression is not a list that contains at 
least n elements. 

0 Sets edit chain to cdr of edit chain, thereby 

making the next higher expression be the new 
current expression. Generates an error if there 
is no higher expression, i.e. cdr of edit chain is 
NIL. 

Note that 0 usually corresponds to going back to the next higher left 
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Occasionally the user can get the edit chain into a state where lastail 
cannot resolve the ambiguity, for example if there were two non-atomic 
structures in the same expression that were eg, and the user descended more 
than one level into one of them and then tried to come back out using UP. 
In this case, UP prints LOCATION UNCERTAIN and generates an error. Of 
course, we could have solved this problem completely in our Implementation 
by saving at each descent dot A elements and tails. However, this would be 
a costly solution to a situation that arises infrequently, and when it 
does, has no detrimental effects. The lastail solution is cheap and 
resolves 99X of the ambiguities. 
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parenthesis, but not always. For example, if the current expression is 
(A B C D E F B), and the user perfoms: 



«3 UP P 

... C D E F G) 

•3 UP P 

... E F G) 

«0 P 

... C D E F G ) 

If the intention is to go back to the next higher left parenthesis, regardless 
of any intervening tails, the command 10 can be used.'"' 

fO does repeated O's until it reaches a point where 

thci current expression is not a tail of the next 
higher expression, i.e., always goes back to the 
next higher left parenthesis. 

t sets edit chain to last of edit chain, thereby 

making the top level expression be the current 
expression. Never generates an error. 

14 

NX effectively does an UP followed by a 2,'* thereby 

making the current expression be the next 
expression. Generates an error if the current 
expression is the last one in a list. (However, 
!NX described below will handle this case.) 

BK makes the current expression be the previous 



1 ? 

!0 is pronounced bang-zero. 

Both NX and BK operate by performing a !0 followed by an appropriate 
number, I.e. there won't be an extra tail above the new current expression, 
as there would be if NX operated by performing an UP followed by a 2. 
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expression in the next higher expression. 
Generates an error if the current expression is 
the first expression in a list. 



For example* if the current expression is (CONO ((NULL X) (RETURN Y))): 



*F RETURN P 
(RETURN Y) 
«BK P 
(NULL X) 



(NX n) n > 1 



equivalent to n NX comnands, except if an error 
occurs, the edit chain is not changed. 



(BK n) n > 1 



equivalent to n BK comnands, except if an error 
occurs, the edit chain is not changed. 



Note: (NX -n) is equivalent to (BK n), and vice versa. 



!NX 



makes current expression be the next expression at 
a higher level, i.e., goes through any number of 
right parentheses to get to the next expression. 
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For example: 



(PROG ((L L) 

(UF D) 
LP (COND 

((NULL (SETQ L (CDR L))) 

(ERROR! )) 
([NULL (CDR (FHEHB (CAR L) 

(CADR L] 

(GO LP))) 
(EOITCOM (QUOTE NX)) 
(SETQ UNFIND UF) 
(RETURN D) 

*F COR P 
(CDR L) 
•NX 



NX 7 
«»NX P 
(ERROR!) 
*!NX P 

((NULL &) (GO LP)) 
«!NX P 

(EDITCOH (QUOTE NX)) 



■NX operates by doing O's until it reaches a stage where the current expression 
is not the last expression in the next higher expression* and then does a NX. 
Thus !NX always goes through at least one unmatched right parenthesis » and the 
new current expression is always on a different level, i.e., !NX and NX always 
produce different results. For example using the previous current expression: 



«F CAR P 
(CAR L) 
*!NX P 
(GO LP) 
«\P P 
(CAR L) 
*NX P 
(CADR L) 



(NTH n) n i( 0 equivalent to n followed by UP, i.e., causes the 

list starting with the nth element of the current 
expression (or nth from the end if n < 0) to 
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become the current express Ion. Causes an error 
if current expression does not have at least n 
elements. 

A generalized form of NTH using location specifications is described on pago 
9.32. 



9.3.2 Commands That Search 

All of the editor commands that search use the same pattern matching routine.' 
We will therefore begin our discussion of searching by describing the pattern 
natch mechanism. A pattern £at matches with x if : 

1. gajt is §3 to X. 

2. pat is 8t. 

3. pat is a number and eqp to x. 

4. pat is a string and strequal[pat;x] is true. 

5. If car[pat] is the atom *ANY*» cdr[pat] is a list of patterns and 
pat matches x if and only if one of the patterns on cdrCpat] 
matches x. 

6a. If pat is a literal atom or string containing one or more alt- 
modes, each $ can match an indefinite number (including 0) of 
contiguous characters in a literal atom or string, e.g. 
VER$ matches both VERYLONGATON and 
"VERYLONGSTRING" as do SLONGS (but not 
SLONG), and SVSLSTS. 



16 
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(NTH 1) is a NOP, as is (NTH -n) where n is the length of the current 
expression. 

This routine is available to the user directly, and is described on page 
9.88. 
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6b. If gat is a literal atom or string ending in two alt-modes, £at 
matches with the first atom or string that is "close" to £at» in 
the sense used by the spelling corrector (Section 17). E.g. 
CONSSSS matches with CONS, CNONCSS with NCONC or NCONCi. 
The pattern matching routine always types a message of the form 
sx to inform the user of the object matched by a pattern of type 
6a or 6b, e.g. -VERYLONGATOM . 

7. If car[pat] Is tho atom pat matches x if 

a. cdr[pat]sNIL„ i.e. pat s( — ), e.g. 

(A — ) matches (A) (A B C) and (A . B) 

In other words, can match any tail of a list. 

b. cdr[pat] matches with some tail of x, 

e.g. (A (A)) will match with (ABC (0)), 
but not (A B C 0), or (ABC (0) E). However, 
note that (A (&) --) will match with 
(ABC (0) E). 

In other words, -- can match any interior segment of a list. 

8. If car[pat] is the atom £at matches x if and only if cdr[pat] 
is eg to x*^* 

9. Otherwise if x is a list, £at matches x if carCpat] 
matches car[x], and cdr[pat] matches cdr[x]. 

When the editor is searching, the pattern matching routine is called to match 

with elements in the structure,, unless the pattern begins with in which 

case cdr of the pattern Is matched against proper tails in the structure. Thus 
if the current expression is (A B C (B C)), 



unless editquletflg «T. 



Pattern 6 Is for use by programs that call the editor as a subroutine, 
since any non-atomic expressilon in a command ti/ped in by the user obviously 
cannot be eg to already existing structure. 



9.22 



*F (B ") 

*P (B C) 

*0 F (... B — ) 

*P 

... B C (B C)) 

Matching ts also attenpted with atonic tails (except for NIL). Thus 
*P 

(A (B . O) 
«F C 

. • . . C ) 

Although the current expression is the atom C after the final command, it is 
printed as ... . C) to alert the user to the fact that C is a tail, not an 
element. Note that the pattern C will match with either instance of C in 
(A C (B . C))t whereas (. .. • C) will natch only the second C. The pattern NIL 
will only match with NIL as an elenent, i.e. it will not natch in (A B), even 
though cddr of (A B) is NIL. However, (... . NIL) (or equivalently (...)) nay 
be used to specify a NIL tail, e.g. (... . NIL) will match with cdr of the 
third subexpression of ((A . B) (C . 0) (E)). 

Search Algorithm 

Searching begins with the current expression and proceeds in print order. 
Searching usually means find the next instance of this pattern, and 
consequently a match is not attempted that would leave the edit chain 
unchanged. At each step, the pattern is matched against the next element in 
the expression currently being searched, unless the pattern begins with ... in 
which case it is matched against the next tail of the expression. 



However, there is a version of the find command which can succeed and leave 
the current expression unchanged (see page 9.26). 
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If the match is not successful, the search operation is recursive first in the 
car direction and then in the cdr direction » i.e., if the element under 
examination is a list, the search descends into that list before attempting to 

on 

match with other elements (or tails) at the same level. 

However, at no point is the total recursive depth of the search (sum of number 
of car s and cdr s descended into) allowed to exceed the value of the variable 
maxlevel . At that point, the search of that element or tail is abandoned, 
exactly as though the element or tail had been completely searched without 
finding a match, and the search continues with the element or tail for which 
the recursive depth is below maxlevel . This feature is designed to enable the 
user to search circular list structures (by setting maxlevel small), as well as 
protecting him from accidentally encountering a circular list structure in the 
course of normal editing, maxlevel is initially set to 300. 

If a successful match is not found in the current expression, the search 
automatically ascends to the next higher expression, and continues searching 
there on the next expression after the expression it Just finished searching. 
If there is none, it ascends again, etc. This process continues until the 
entire edit chain has been searched, at which point the search fails, and an 
error is generated. If the search fails (or, what is equivalent, is aborted by 
control-E), the edit chain is not changed (nor are any conses performed). 

If the search is successful, i.e., an expression is found that the pattern 
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There Is also a version of the find command (see page 9.27) which only 
attempts matches at the top level of the current expression, i.e., does not 
descend into elements, or ascend to higher expressions. 

maxlevel can also be set to NIL, which is equivalent to infinity. 

See footnote on page 9.24. 
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matches, the edit chain is set to the value it would have had had the user 
reached that expression via a sequence of integer coiiinands. 

If the expression that matched was a list, it will be the final link in the 
edit chain, i.e., the new current expression. If the expression that matched 
is not a list, e.g., is an aton, the current expression will be the tail 
beginning with that aton,^^ i.e., that atom will be the first element in the 
new current expression. In other words, the search effectively does an UP,^ 

Search Commands 

All of the commands below set lastail for use by UP, set unf ind for use by \ 
(page 9.35), and do not change the edit chain or perform any conses if thoy 
are unsuccessful or aborted. 

F pattern i.e., two commands: the F informs the editor that 

the next command is to be interpreted as a 
pattern. This is the most common and useful form 
of the find command. If successful, the edit 
chain always changes, i.e., F pattern means find 
the next instance of pattern . 

If memb[ pattern ;current-expression] is true, F 
does not proceed with a full recursive search. If 
the value of the merob is NIL, F invokes the search 
algorithm described earlier. 



^ Unless the atom is a tail, e.g. B in (A . B). In this case, the current 

expression will be 6, but will print as .... 6). 

Unless upfindflg »NIL (initially set to T). For discussion, see page 
9.43-44. 
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Thus if the current expression is 

(PROG NIL LP (COND (-- (GO LPl)]l) ... LPl ...), F LPl will find the prog label, 
not the LPl inside of the GO expression, even though the latter appears first 
(in print order) in the current expression. Note that 1 (making the atom PROG 
be the current expression), followed by F LPl would find the first LPl. 

(F pattern N) same as F pattern, i.e., finds the next instance 

of pattern, except the memb check of F pattern is 
not performed. 

(F pattern T) Similar to F pattern, except may succeed without 

changing edit chain, and does not perform the memb 
check. 

Thus if the current expression is (COND ..), F COND will look for the next 
COND, but (F COND T) will *stay here*. 

(F pattern n) n > 1 Finds the nth place that pattern matches. 

Equivalent to (F pattern T) followed by 
(F pattern N) repeated n-1 times. Each time 
pattern successfully matches, n is decremented by 
i, and the search continues, until n reaches 0. 
Note that the pattern does not have to match with 
n identical expressions; it Just has to match n 
times. Thus if the current expression is 
(FOOi F002 F003), (F FOOS 3) will find F003. 
If the pattern does not match successfully n 
times, an error is generated and the edit chain is 
unchanged (even if the pattern matched n-1 times). 
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(F pattern) or only matches with elements at the 

(F pattern NIL) top level of the current expression, i.e., the 

search will not descend into the current 
expression, nor will it go outside of the current 
expression. Nay succeed without changing edit 
chain. 



For example, if the current expression is 

(PROG NIL (SETQ X (CONO & &)) (COND &) ...), F COND will find the COND inside 
the SETQ, whereas (F (COND — )) will find the top level CONO, i.e., the second 
one. 



(FS pattern I ... pattern^) 



equivalent to F pattern^ followed by F 
pattern2 followed by F patternj^, so that if F 
patterngi fails, edit chain is left at place 
patterngj.l matched. 



(F" expression x) 



equivalent to (F (>» . expression) x), i.e., 
searches for a structure e§ to expression, see 
page 9.22. 



(ORF pattern^ ... pattern|^) equivalent to (F (*ANY* pattern| ... pattern|^) N), 

i.e., searches for an expression that is matched 
by either pattern |, pattern2» ... or pattern^. 
See page 9.21. 



BF pattern 



backwards find. Searches in reverse print order, 
beginning with expression immediately before the 
current expression (unless the current expression 
is the top level expression, in which case BF 
searches the entire expression, in reverse order)* 
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BF uses the same pattern match routine as F, and 
maxlevel and upfindflg have the same effect, but 
the searching begins at the end of each list, and 
descends into each element before attempting to 
match that element. If unsuccessful* the search 
continues with the next previous element, etc., 
until the front of the list is reached, at which 
point BF ascends and backs up, etc. 

For example, if the current expression is 

(PROG NIL (SETO X (SETQ Y (LIST Z))) (COND ((SETQ W — ) --)) — ), F LIST 
followed by BF SETQ will leave the current expression as (SETQ Y (LIST Z)), as 
will F COND followed by BF SETQ. 

(BF pattern T) search always includes current expression, i.e., 

starts at the end of current expression and works 
backward, then ascends and backs up, etc. 

Thus in the previous example, where F COND followeBF SETQ found 
(SETQ Y (LIST Z)), F COND followed by (BF SETQ T) would find the (SETQ W --) 
expression. 

(BF pattern) same as BF pattern. 

(BF pattern NIL) 

Location Specification 

Many of the more sophisticated commands described later in this chapter use a 
more general method of specifying position called a location specification . A 
location specif ication is a list of edit commands that are executed in the 
normal fashion with two exceptions. First, all commands not recognized by the 
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editor are interpreted as though they had been preceded by F. For example, 
the location specification (CONO Z 3) specifies the 3rd elenent in the first 
clause of the next COND.^^ 

Secondly, if an error occurs while evaluating one of the commands in the 
location specification, and the edit chain had been changed, i.e., was not the 
same as it was at the beginning of that execution of the location 
specification, the location operation will continue. In other words, the 
location operation keeps going unless it reaches a state where it detects that 
it is 'looping', at which point it gives up. Thus, if (COND 2 3) is being 
located, and the first clause of the next COND contained only two elements, the 
execution of the command 3 would cause an error. The search would then 
continue by looking for the next COND. However, if a point were reached where 
there were no further CONDs, then the first command, COND, would cause the 
error; the edit chain would not have been changed, and so the entire location 
operation would fail, and cause an error. 

The IF command in conjunction with the ## function provide a way of using 
arbitrary predicates applied to elements in the current expression. IF and ## 
will be described in detail later in the chapter, along with examples 
illustrating their use in location specifications. 

Throughout this chapter, the meta-symbol 9 is used to denote a location 
specification. Thus 9 is a list of commands interpreted as described above. 9 
can also be atomic, in which case it is interpreted as list[9]. 
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Normally such commands would cause errors. 

Note that the user could always write F COND followed by 2 and 3 for 
(COND 2 3) if he were not sure whether or not CONO was the name of an 
atomic command. 
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(LC . 9) 



provides a way of explicitly invoking the location 
op«ration, e.g. (LC COND 2 3) will perform the the 
search described above. 



(LCL . 9) Same as LC except the search is confined to the 

current expression, i.e., the edit chain is 
rebound during the search so that it looks as 
though the editor were called on Just the current 
expression. For example, to find a CONO 
containing a RETURN, one might use the location 
specification (COND (LCL RETURN) \) where the \ 
would reverse the effects of the LCL command, and 
make the final current expression be the CONO. 

(2ND . 9) Same as (LC . 9) followed by another (LC . 9) 

except that if the first succeeds and second 
fails, no change is made to the edit chain. 

(3RD . 9) Similar to 2ND. 

(«• pattern) ascends the edit chain looking for a link which 

matches pattern . In other words, it keeps doing 
O's until it gets to a specified point. If 
pattern is atomic, it is matched with the first 
element of each link, otherwise with the entire 
link.^^ 



If pattern is of the form (IF expression), expression is evaluated at each 
link, and if its value is NIL, or the evaluation causes an error, the 
ascent continues. 
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For example: 



[PROG NIL 

(COND 

[(NULL (SETQ L (COR L))) 
(COND 

(FL6 (RETURN L] 
([NULL (COR (FMEHB (CAR L) 

(CADR L]] 

«F CADR 
*(T COND) 
«P 

(COND (& &) (& &)) 



Note that this command differs from BF in that it does not search inside of 
each link, it simply ascends. Thus in the above example, F CADR followed by 
BF COND would find (COND (FLG (RETURN LM). not the higher COND. 

If no match is found, an error is generated, and 
the edit chain is unchanged. 

(BELOW com x) ascends the edit chain looking for a link 

specified by com , and stops links below 

that,^^ i.e. BELOW keeps doing 0*s until it gets 
to a specified point, and then backs off x O's. 

(BELOW com) same as (BELOW com 1). 

For example, (BELOW COND) will cause the cond clause containing the current 
expression to become the new current expression. Thus if the current 
expression is as shown above, F CADR followed by (BELOW COND) will make the new 



x is evaluated, e.g., (BELOW com (IPLUS X Y). 

Only links that are elements are counted, not tails. 
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expression be ([NULL (COR (FHENB (CAR L) (CADR L] (GO LP)), and is therefore 
equivalent to 0 0 0 0. 

The BELOW command is useful for locating a substructure by specifying something 
it contains. For example, suppose the user is editing a list of lists, and 
wants to find a sublist that contains a FOO (at any depth). He simply executes 
F FOO (BELOW \). 

(NEX X) same as (BELOW x) followed by NX. 

For example, if the user is deep inside of a SELECTQ clause, he can advance to 
the next clause with (NEX SELECTQ). 

NEX same as (NEX «-). 

The atomic form of NEX is useful if the user will be performing repeated 
executions of (NEX x). By simply MARKing (see page 9.34) the chain 
corresponding to x, he can use NEX to step through the sublists. 

(NTH x) generalized NTH command. Effectively performs 

(LCL . X), followed by (BELOW \), followed by UP. 

In other words, NTH locates x, using a search restricted to the current 
expression, and then backs up to the current level, where the new current 
expression is the tail whose first element contains, however deeply, the 
expression that was the terminus of the location operation. For example: 

«P 

(PROG (& &) LP (COND & &) (EDITCON &) (SETQ UNFIND UF) (RETURN L)) 

"(NTH UF) 

*P 

... (SETQ UNFIND UF) (RETURN L)) 
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If tho search is unsuccessful, NTH generates an 
error and the edit chain is not changed. 

Note that (NTH n) is just a special case of (NTH x), and in fact, no special 
check is made for x a number; both commands are executed identically. 

e.g., (COND .. RETURN). Finds a cond that 
contains a return , at any depth. Equivalent to 
(but more efficient than) (1^ pattern N), (LCL . 9) 
followed by («- pattern). 

For example, if the current expression is 

(PROG NIL [COND ((NULL L) (COND (FLG (RETURN L] — ), then (CONO .. RETURN) will 
make (COND (FLG (RETURN L))) be the current expression. Note that it is the 
innermost COND that is found, because this is the first CONO encountered when 
ascending from the RETURN. In other words, (pattern .. 9) is not always 
equivalent to (F pattern N), followed by (LCL . 9) followed by \. 

Note that 9 is a location specification, not Just a pattern. Thus 
(RETURN .. COND 2 3) can be used to find the RETURN which contains a COND 
whose first clause contains (at least) three elements. Note also that since 9 
permits any edit command, the user can write commands of the form 
(COND .. (RETURN .. COND)), which will locate the first COND that contains a 
RETURN that contains a COND. 



(pattern .. 9)^^ 



An infix command, is not a meta-symbol, it is the name of the command. 

9 is cddr of the command. 
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9.3.3 Commands That Save and Restore The Edit Chain 



Several facilities are available for saving the current edit chain and later 
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retrieving it: NARK, which marks the current chain for future reference, «-» 
which returns to the last nark without destroying it, and which returns to 
the last mark and also erases it. 

NARK adds the current edit chain to the front of the 

list marklst. 

makes the new edit chain be (CAR NARKLST). 
Generates an error if marklst is NIL, i.e., no 
NARKs have been performed, or all have been 
erased. 

«-«- similar to but also erases the NARK, i.e., 

performs (SETQ NARKLST (COR NARKLST)). 

Note that if the user has two chains marked, and wishes to return to the first 
chain, he must perform which removes the second mark, and then •-. However, 
the second mark is then no longer accessible. If the user wants to be able to 
return to either of two (or more) chains, he can use the following generalized 
NARK : 

(NARK atom) sets atom to the current edit chain, 

(\ atom) makes the current edit chain become the value of 

atom. 



An atomic command; do not confuse with the list command («- pattern). 
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If the user did not prepare in advance for returning to a particular edit 
chain, he may still be able to return to that chain with a single conmand by 
using \ or \P. 

\ makes the edit chain be the value of unfind. 

Generates an error if unfind «HIt« 

unfind is set to the current edit chain by each command that makes a "big 
jump", i.e., a command that usually performs more than a single ascent or 
descent, namely «-, (NX, all commands that involve a search* e.g., f, LC, 
.., BELOW, et al and \ and \P themselves. 

For example, if the user types F COND, and then F CAR, \ would take hin back to 
the COND. Another \ would take him back to the CAR, etc. 

\P restores the edit chain to its state as of the 

last print operation, i.e. P, 7, or PP. If the 
edit chain has not changed since the last 
printing, \P restores it to its state as of the 
printing before that one, 'i.e., two chains are 
always saved. 

For example, if the user types P followed by 3 2 I P, \P will return to the 
first P, i.e., would be equivalent to 0 0 0.^^ Another \P would then take hin 
back to the second P, i.e., the user could use \P to flip back and forth 
between the two edit chains. 



Except that unfind is not reset when the current edit chain is the top 
level expression, since this could always be returned to via the t command. 

Note that if the user had typed P followed by F COND, he could use either \ 
or \P to return to the P, i.e., the action of \ and \P are independent. 
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(S var . 9) Sets var (using setq ) to the current expression 

after performing (LC . 9). Edit chain is not 
changed. 

Thus (S FOO) will set foo to the current expression, (S FOO -1 1) will set foo 
to the first element in the last element of the current expression. 

This ends the section on "Attention Changing Commands." 

9.4 Commands That Modify Structure 

The basic structure modification commands in the editor are: 

(n) n > 1 deletes the corresponding element from the 

current expression. 

(n e^ ... e^) n,m > 1 replaces the nth element in the current 

expression with e^ ... e^. 

(-n Q| ... e^) n,m > 1 inserts e^ ... e^^ before the nth element 

in the current expression. 

(N e^ ... o^) m > 1 attaches e| ... e^^ at the end of the current 

expression. 

As mentioned earlier: 

all structure modification done by the editor is destructive, i.e. the editor 
uses rplaca and rplacd to physicallu change the structure it was given. 

However, all structure modification is undoable, see UNDO page 9.78. 
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All of the above commands generate errors if the current expression is not a 
list, or in the case of the first three commands, if the list contains fewer 
than n elements. In addition, the command (1), i.e. delete the first element, 
will cause an error if there is only one element, since deleting the first 
element must be done by replacing it with the second element, and then deleting 
the second element. Or,, to look at it another way, deleting the first element 
when there is only one element would require changing a list to an atom (i.e. 
to NIL) which cannot be done.^ 

9.4.1 Implementation of Structure Modification Commands 

Motet Since all commands that insert, replace^ delete or attach structure use 
the same low level editor functions t the remarks made here are valid for 
all structure changing conmiands. 

For all replacement, insertion, and attaching at the end of a list, unless the 
command was typed in directly to the editor, copies of the corresponding 
structure are used, because of the possibility that the exact same command, 
(i.e. same list structure) might be used again. Thus if a program constructs 
the command (1 (A B C)) e.g. via (LIST 1 FOO), and gives this command to the 
editor, the (ABC) used for the replacement will not be eg to foo .*"' 



However, the command DELETE will work even if there is only one element in 
the current expression, since it will ascend to a point where it can do the 
deletion. 



Some editor commands take as arguments a list of edit commands, e.g. 
(LP F FOO (1 (CAR FOO))). In this case, the command (1 (CAR FOO)) is not 
considered to have been "typed in" even though the LP command itself may 
have been typed in. Similarly, commands originating from macros, or 
commands given to the editor as arguments to editf, edity, et al, e.g. 
E0ITF(F0O F COND (N — )) are not considered typed in. 



The user can circumvent this by using the I command, which computes the 
structure to be used. In the above example, the form of the command would 
be (I 1 FOO), which would replace the first element with the value of foo 
itself. See page 9.62. 



9.37 



The rest of this section is included for applications wherein the editor is 
used to modify a data structure, and pointers into that data structure are 
stored elsewhere. In these cases, the actual mechanics of structure 
modification must be known in order to predict the effect that various commands 
may have on these outside pointers. For example, if the value of foo is cdr of 
the current expression, what will the commands (2), (3), (2 X Y Z), (-2 X Y Z), 
etc. do to foo ? 

Deletion of the first element in the current expression is performed by 
replacing it with the second element and deleting the second element by 
patching around it. Deletion of any other element is done by patching around 
it, i.e., the previous tail is altered. Thus if foo, is eg to the current 
expression which is (A 8 C 0), and fie is cdr of foo, after executing the 
command (I), fog will be (B C D) (which is equal but not eg to fie). However, 
under the same initial conditions, after executing (2) fie will be unchanged, 
i.e., fie will still be (B C D) even though the current expression and foo are 
now (A C D).^'' 

Both replacement and insertion are accomplished by smashing both car and cdr of 
the corresponding tail. Thus„ if foo were eg to the current expression, 
(ABC D), after (1 X Y Z), foo would be (X Y Z 6 C D). Similarly, if foo were 
eg to the current expression, (ABC D), then after (-1 X Y Z), foo would be 
(X Y Z A B C D). 

The N command is accomplished by smashing the last cdr of the current 



A general solution of the problem Just isn't possible, as it would require 
being able to make two lists eg to each other that were originally 
different. Thus if fie is cc^ of the current expression, and fum is cddr 
of the current expression, performing (2) would have to make fie be eg to 
fum if all subsequent operations were to update both fie and fum correctly. 
Think about it. 
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expression a la nconc. Thus if foo were eg to any tail of the current 
expression, after executing an N connand, the corresponding expressions would 
also appear at the end of foo. 

In summary, the only situation in which an edit operation will not change an 
external pointer occurs when the external pointer is to a proper tail of the 
data structure, i.e., to cdr of some node in the structure, and the operation 
is deletion. If all external pointers are to elements of the structure, i.e., 
to car of some node, or if only insertions, replacements, or attachments are 
performed, the edit operation will always have the same effect on an external 
pointer as it does on the current expression. 

9.4.2 The A. B. and ; Commands 

In the (n), (n e^ ... e^), and (-n e^ ... e^) commands, the sign of the 
integer is used to indicate the operation. As a result, there is no direct way 
to express insertion after a particular element, (hence the necessity for a 
separate N command). Similarly, the user cannot specify deletion or 
replacement of the nth element from the end of a list without first converting 
n to the corresponding positive integer* Accordingly, we have: 

inserts e^ ... e^^ before the current expression. 
Equivalent to UP followed by (*1 e| ... e^). 

For example, to insert FOO before the last element in the current expression, 
perform -1 and then (B FOO). 

(A e^ ... e^g) inserts e| ... e^^ after the current expression. 

Equivalent to UP followed by (-2 e^ ... e^^) or 
(N e^ ... e.) whichever is appropriate. 



(B ej ... e^) 
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( : e| ... e^) replaces the current expression by e^ . . . 9^, 

Equivalent to UP followed by (1 e^ ... e^^). 

DELETE, or (:) deletes the current expression. 

DELETE first tries to delete the current expression by performing an UP and 
then a (1). This works In most cases. However* If after performing UP, the 
new current expression contains only one element, the command (1) will not 
work. Therefore, DELETE starts over and performs a 6K, followed by UP, 
followed by (2). For example, If the current expression is 
(COND ((MEMB X Y)) (T Y)), and the user performs -1, and then DELETE, the 
BK-UP-(2) method is used, and the new current expression will be ... 
((NENB X Y))) 

However, if the next higher expression contains only one element, BK will not 
work. So in this case, DELETE performs UP, followed by (: NIL), i.e., it 
replaces the higher expression by NIL. For example, if the current expression 
is (COND ((MEMB X Y)) (T Y)) and the user performs F MEMB and then DELETE, the 
new current expression will be ... NIL (T Y)) and the original expression would 
now be (COND NIL (T Y)). The rationale behind this is that deleting (MEMB X Y) 
from ((MEMB X Y)) changes a list of one element to a list of no elements, i.e., 
() or NIL. 

If the current expression is a tail, then B, A, :, and DELETE all work exactly 
the same as though the current expression were the first element in that tail. 
Thus If the current expression were ... (PRINT Y) (PRINT Z)), (6 (PRINT X)) 
would Insert (PRINT X) before (PRINT Y), leaving the current expression 
... (PRINT X) (PRINT Y) (PRINT Z)). 
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The following forms of the A, 6, and ; cominands incorporate a location 
specification: 



(INSERT e^ ... e^ BEFORE . 9)^^ Similar to (LC .9)^^ followed by (B 



(PROG (& & X) ««COMMENT>>'« (SELECTQ ATH & NIL) (OR & &) (PRINl & T) 
(PRINl & T) (SETQ X & 

*( INSERT LABEL BEFORE PRINl) 
*P 

(PROG (& & X) **COMNENT«* (SELECTQ ATH & NIL) (OR & &) LABEL 
(PRINl & T) ( 
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Current edit chain is not changed, but unfind is 
set to the edit chain after the B was performed, 
i.e. \ will make the edit chain be that chain 
where the insertion was performed. 

(INSERT ... e^ AFTER . 9) Similar to INSERT BEFORE except uses A instead of 

B. 

(INSERT e| ... FOR . 9) similar to INSERT BEFORE except uses : for B. 
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i.e. 9 is cdr[member[ BEFORE; command]] 

except that if 9 causes an error, the location process does not continue as 
described on page 9.29. For example if 9s(C0ND 3) and the next COND does 
not have a 3rd element, the search stops and the INSERT fails. Note that 
the user can always write (LC COND 3) if he intends the search to continue. 

Sudden termination of output followed by a blank line return Indicates 
printing was aborted by control-E. 



9.41 



(REPLACE 9 WITH . . . e^r^ Here 9^^ Is the ^earaent of the command between 

REPLACE and WITH. Same as 

(INSERT e^ ... e^ FOR . 9). 

Example: (REPLACE COND -1 WITH (T (RETURN L))) 



(CHANGE e TO e^ ... e^) Sane as REPLACE WITH. 

(DELETE . e) does a (LC . 9)"^^ followed by DELETE. Current 

edit chain is not changed, but unfind is set to 
the edit chain after the DELETE was performed. 

Example: (DELETE -1), (DELETE COND 3) 

motet if 0 is MIL (i.e. empty) ^ the corresponding operation is performed here 
(on the current edit chain). 



For example, (REPLACE WITH (CAR X)) is equivalent to (: (CAR X)). For added 
readability. HERE is also permitted, e.g. (INSERT (PRINT X) BEFORE HERE) will 
insert (PRINT X). before the current expression (but not change the edit 
chain) . 



BY can be used for WITH. 



See footnote on page 9.41 
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See footnote on page 9.41. 

Unless the current expression is no longer a part of the expression being 
edited, e.g. if the current expression is ... C) and the user performs 
(DELETE i), the tail, (C), will have been cut off. Similarly, if the 
current expression is (CDR Y) and the user performs (REPLACE WITH (CAR X)). 
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Notet & does not have to specify a location within the current expression^ i.e. 
it is perfectly legal to ascend to INSERT, REPLACE, or DELETE 

For example, (INSERT (RETURN) AFTER t PROG -1) will go to the top, find the 
first PROG, and insert a (RETURN) at its end, and not change the current edit 
chain. 

The A, B, and : commands, commands, (and consequently INSERT, REPLACE, and 
CHANGE), all make special checks in e| thru e^^ for expressions of the form (## 
. corns). In this case, the expression used for inserting or replacing is a 
copy of the current expression after executing corns , a list of edit commands. 
For example, (INSERT (## F COND -1 -1) AFTER 3)^^ will make a copy of the last 
form in the last clause of the next cond . and insert it after the third element 
of the current expression. 

9.4.3 Form Oriented Editing and the Role of UP 

The UP that is performed before A, B, and : commands^^ makes these operations 
form-oriented. For example, if the user types F SETOt and then DELETE, or 
simply (DELETE SETQ), he will delete the entire SETQ expression, whereas 
(DELETE X) if X is a variable, deletes just the variable X. In both cases, the 
operation is performed on the corresponding form, and in both cases is probably 
what the user intended. Similarly, if the user types 

(INSERT (RETURN Y) BEFORE SETQ), he means before the SETQ expression, not 



45 

The execution of coms does not change the current edit chain. 

ATot (INSERT F COND -1 (## -1) AFTER 3), which inserts four elements after 
the third element, namely F, COND, -1, and a copy of the last element in 
the current expression. 

and therefore in INSERT, CHANGE, REPLACE, and DELETE commands after the 
location portion of the operation has been performed. 
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before the atom SETQ.^^ A consequent of this procedure is that a pattern of the 
form (SETQ Y --) can be viewed as simply an elaboration and further refinement 
of the pattern SETQ. Thus (INSERT (RETURN Y) BEFORE SETQ) and 
(INSERT (RETURN Y) BEFORE (SETO Y ")) perform the same operation^^ and, in 
fact, this is one of the motivations behind making the current expression after 
F SETQ, and F (SETQ Y — ) be the same. 

Occasionally, however, a user may have a data structure in which no special 
significance or meaning is attached to the position of an atom in a list, as 
INTERLISP attaches to atoms that appear as car of a list, versus those 
appearing elsewhere in a list. In general, the user may not even know whether 
a particular atom is at the head of a list or not. Thus, when he writes 
(INSERT expression BEFORE FOO), he means before the atom F(X), whether or not it 
is car of a list. By setting the variable upf indflg to NIL," the user can 
suppress the implicit UP that follows searches for atoms, and thus achieve the 
desired effect. With upfindf Ig aNIL, following F FOO, for example, the current 
expression will be the atom FOO. In this case, the A, B, and : operations will 
operate with respect to the atom FOO. If the user intends the operation to 
refer to the list which FOO heads, he simply uses instead the pattern (FOO — ). 
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There is some ambiguity in (INSERT expr AFTER functionname) , as the user 
might mean make expr be the function's first argument. Similarly, the user 
cannot write (REPLACE SETQ WITH SETQQ) meaning change the name of the 
function. The user must in these cases write (INSERT expr AFTER 
functioname 1), and (REPLACE SETQ 1 WITH SETQQ). 

assuming the next SETQ is of the form (SETQ Y — ). 

Initially, and usually, set to T. 
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9.4. 4 Extract and Embed 



Extraction involves replacing the current expression with one of its 
subexpressions (from any depth). 

(XTR .9) replaces the original current expression with the 

expression that is current after performing 
(LCL . 9).^^ 

For example, if the current expression is (CONO ((NULL X) (PRINT Y))), 
(XTR PRINT), or (XTR Z Z) will replace the cond by the print . 

If the current expression after (LCL ,9) is a 
tail of a higher expression, its first element is 
used. 

For example, if the current expression is (CONO ((NULL X) Y) (T Z)), then 
(XTR Y) will replace the cond with Y, even though the current expression after 
performing (LCL Y) is ... Y). 

If the extracted expression is a list, then after 
XTR has finished, the current expression will be 
that list. 



Thus, in the first example, the current expression after the XTR would be 
(PRINT Y). 



See footnote on page 9.41. 
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If the extracted expression is not a list, the new 
current expression will be a tail whose first 
element is that non-list. 

Thus, in the second example, the current expression after the XTR would be 
... Y followed by whatever followed the COND. 

If the current expression initially is a tail, extraction works exactly the 
same as though the current expression were the first element in that tail. 
Thus if the current expression is ... (COND ((NULL X) (PRINT Y))) (RETURN Z)), 
then (XTR PRINT) will replace the cond by the print , leaving (PRINT Y) as the 
current expression. 

The extract command can also incorporate a location specification: 

(EXTRACT 0j FROM . 9^)^^ Performs (LC . 9^)^ and then (XTR . Current 

edit chain is not changed, but unfind is set to 
the edit chain after the XTR was performed. 

Example: If the current expression is (PRINT (COND ((NULL X) Y) (T Z))) then 
following (EXTRACT Y FROM COND), the current expression will be (PRINT Y). 
(EXTRACT 2 -1 FROM COND), (EXTRACT Y FROM 2), (EXTRACT 2 -1 FROM 2) will all 
produce the same result. 



9| is the segment between EXTRACT and FROM. 
See footnote on page 9.41. 
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While extracting replaces the current expression by a subexpression, embedding 
replaces the current expression with one containing it as a subexpression. 



(NBD e^ ... e^) MBD substitutes^ the current expression for all 

instances of the atom * in e^ ... e^g, and replaces 
the current expression with the result of that 
substitution. 

Examples: If the current expression is (PRINT Y), 

(MBD (COND ((NULL X) *) ((NULL (CAR Y)) * (GO LP)))) would replace (PRINT Y) 
with (COND ((NULL X) (PRINT Y)) ((NULL (CAR Y)) (PRINT Y) (60 LP))). 

If the current expression is (RETURN X), (MBD (PRINT Y) (AND FLG *)) would 
replace it with the tu;o expressions (PRINT Y) and (AND FLG (RETURN X)) i.e., if 
the (RETURN X) appeared in the cond clause (T (RETURN X)), after the NBD, the 
clause would be (T (PRINT Y) (AND FLG (RETURN X))). 

If * does not appear in e^ ... e^, the MBD is 
interpreted as (MBD (e^ ... e^ *)). 

Examples: If the current expression is (PRINT Y), then (MBD SETQ X) will 
replace it with (SETQ X (PRINT Y)). If the current expression is (PRINT Y), 
(MBD RETURN) will replace it with (RETURN (PRINT Y)). 

MBD leaves the edit chain so that the larger expression is the new current 
expression. 



as with subst , a fresh copy is used for each substitution. 
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If the current expression initially is a tail, embedding works exactly the same 
as though the current expression were the first element in that tail. Thus if 
the current expression were ... (PRINT Y) (PRINT Z)), (NBD SETQ X) would 
replace (PRINT Y) with (SETQ X (PRINT Y)). 

The embed command can also incorporate a location specification: 

does (LC . 9)^ and then (NBD . x). Edit chain is 
not changed, but unfind is set to the edit chain 
after the NBD was performed. 

Example: (EMBED PRINT IN SETQ X), (ENBED 3 2 IN RETURN), 
(EMBED COND 3 1 IN (OR * (NULL K))). 

WITH can be used for IN, and SURROUND can be used for EMBED, e.g., (SURROUND 
NUMBERP WITH (AND * (NINUSP X));i. 

9.4.5 The HOVE Command 

The MOVE command allows the user to specify (1) the expression to be moved, (2) 
the place it is to be moved to, and (3) the operation to be performed there, 
e.g., insert it before, insert it after, replace, etc. 

(MOVE TO com . 9^)^^ where com is BEFORE, AFTER, or the name of a list 



9 is the segment between EMBED and IN. 

See footnote on page 9.41. 

9 1 is the segment between MOVE and TO. 
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(EMBED 9 IN . x)^^ 
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command, e.g., :, N, etc. performs (LC . 9^), 
and obtains the current expression there (or its 
first element, if it is a tail), which we will 
call expr ; MOVE then goes back to the original 
edit chain, performs (LC . followed by 

(com expr),^^ then goes back to 9| and deletes 
expr . Edit chain is not changed. Unfind Is set 
to edit chain after (com expr) was performed. 

For example, if the current expression is (A B C D), (MOVE 2 TO AFTER 4) will 
make the new current expression be (A C D B). Note that 4 was executed as of 
the original edit chain, and that the second element had not yet been 
removed. 

As the following examples taken from actual editing will show, the HOVE command 
is an extremely versatile and powerful feature of the editor. 



*? 

(PROG ((L D) (EDLOC (CDDR C)) (RETURN (CAR L))) 

*(MOVE 3 TO : CAR) 

*? 

(PROG ((L D) (RETURN (EDLOC (CDDR C)))) 
« 

*P 

... (SELECTQ OBOPR & &) (RETURN &) LP2 (COND & &)) 

"(MOVE 2 TO N 1) 

*P 

. . . (SELECTQ OBJPR & & &) LP2 (COND & &)) 
* 



CO 

see footnote on page 9.41. 

SQ 

Setting an internal flag so expr is not copied. 

60 

If @2 specifies a location inside of the expression to be movedt a message 
is printed and an error is generated, e.g. (NOVE 2 TO AFTER X), where X is 
contained inside of the second element. 
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«p 

(OR (EQ X LASTAIL) (NOT &) (AND & & &)) 

*(MOVE 4 TO AFTER (BELOW CONO)) 

*P 

(OR (EQ X LASTAIL) (NOT &)) 
*\ P 

. . . (& &) (AND & & &) (T & &)) 



«P 

((NULL X) «*COMMENT** (COND & 

*(-3 (GO NXT] 

*(MOVE 4 TO N (•• PROG)) 

*P 

((NULL X) ««COMMENT»* (GO NXT)) 
*\ P 

(PROG (&) «*COMHENT** (COND & & &) (COND & & ft) (CONO & &)) 

*( INSERT NXT BEFORE -1) 

*P 

(PROG (&) **COMNENT** (COND & & A) (COND & & &) NXT (COND & &)) 



Note that in the last example, the user could have added the prog label NXT and 
moved the cond In one operation by performing (HOVE 4 TO N («- PROG) (N NXT)). 
Similarly, in the next example. In the course of specifying the location 
where the expression was to be moved to, the user also performs a structure 
modification, via (N (T)), thus creating the structure that will receive the 
expression being moved. 



«P 

((CDR &) «*COMMENT«« (SETQ CL &) (EDITSMASH CL & &)) 

"MOVE 4 TO N 0 (N (T)) -1] 

*P 

((CDR &) «*COMMENT** (SETQ CL &)) 
*N P 

*(T (EDITSMASH CL & &)) 



If @2 (HERE), the current position specifies where the operation is 

to take place. In this case, unfind is set to where the expression that was 
moved was originally located, i.e. 9^. For example: 



*P 

(TENEX) 

"(MOVE t F APPLY TO N HERE) 
*P 

(TENEX (APPLY & &)) 
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*p 

(PROG (& & & ATM IND VAL) (OR & &) «>*COMMENT>k* (OR & &) (PRINi & T) ( 
PRINl & T) (SETO IND 

Di 

•(MOVE * TO BEFORE HERE) 

(PROG (& & & ATM INO VAL) (OR & &) (OR & &) (PRINl & 
«P 

(T (PRINl C-EXP T)) 

•(MOVE t BF PRINl TO N HERE) 

*P 

(T (PRINl C-EXP T) (PRINl & T)) 



Finally* If 9^ is NIL, the MOVE comnand allows tha user to specify where the 
current expression is to be moved to^ In this case, the edit chain is changecl, 
and is the chain where the current expression was moved to; unfind is set to 
where it was. 



«P 

(SELECTQ OBJPR (&) (PROGN & &)) 

•(MOVE TO BEFORE LOOP) 

•P 

... (SELECTQ OBOPR & &) LOOP (FRPLACA DFPRP &) (FRPLACO DFPRP 
&) (SELECTQ 



9.4.6 Commands That "Hove Parentheses* 

The commands presented in this section permit modification of the list 
structure itself, as opposed to modifying components thereof. Their effect can 
be described as inserting or removing a single left or right parenthesis, or 
pair of left and right parentheses. Of course, there will always be the same 
number of left parentheses as right parentheses in any list structure, since 
the parentheses are Just a notational guide to the structure provided by print . 
Thus, no command can insert or remove Just one parenthesis, but this is 
suggestive of what actually happens. 



Sudden termination of output followed by a blank line indicates printing 
was aborted by control-E. 
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In all six commands, n and n are used to specify an element of a list, usually 
of the current expression. In practice, n and m are usually positive or 
negative integers with the obvious interpretation. However, all six commands 
use the generalized NTH command, page 9.32, to find their element(s), so that 
nth element means the first element of the tail found by performing (NTH n). 
In other words, if the current expression is 

(LIST (CAR X) (SETQ Y (CONS W Z))), then (BI 2 CONS), (BI X -1), and (BI X Z) 
all specify the exact same operation. 

All six commands generate an error if the element is not found, i.e. the NTH 
fails. All are undoable. 

(BI n m) both In, inserts a left parentheses before the nth 

element and after the mth element in the current 
expression. Generates an error if the roth element 
is not contained in the nth tail, i.e., the mth 
element must be "to the right" of the nth element. 

Example: If the current expression is (A B (C D E) F 6), then (61 2 4) will 
modify it to be (A (B (C 0 E) F) 6). 

(BI n) sane as (BI n n). 

Example: If the current expression is (A B (C 0 E) F G), then (BI -2) will 
modify it to be (A B (C 0 E) (F) 6). 

(BO n) both out. Removes both parentheses from the nth 

element. Generates an error if nth element is not 
a list. 

Example: If the current expression is (A B (C D E) F G), then (BO 0) will 
modify it to be (A B C 0 E F G). 



9.52 



(LI n) left in, inserts a left parenthesis before the nth 

element (and a matching right parenthesis at the 
end of the current expression)* i.e. equivalent 
to (61 n -i). 

Example: if the current expression is (A B (C 0 E) F G), then (LI 2) will 
modify it to be (A (B (C 0 E) F 6)). 

(LO n) left out, removes a left parenthesis from the nth 

element. All elements following the nth element 
are deleted* Generates an error if nth element is 
not a list. 

Example: If the current expression is (A B (C 0 E) F 6), then (LO 3) will 
modify it to be (A B C D E). 

(RI n ra) right in, inserts a right parenthesis after the 

mth element of the nth element. The rest of the 
nth element is brought up to the level of the 
current expression. 

Example: If the current expression is (A (B C D E) F G), (RI Z 2) will modify 
it to be (A (B C) D E F G). Another way of thinking about RI is to read it as 
"move the right parenthesis at the end of the nth element in to after its mth 
element." 

(RO n) right out, removes the right parenthesis from the 

nth element, moving it to the end of the current 
expression. All elements following the nth 
element are moved inside of the nth element. 
Generates an error if nth element is not a list. 
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Example: If the current expression is (A B (C 0 E) F G), (RO 3) will modify it 
to be (A B (C D E F G)). Another way of thinking about RO is to read it as 
"move the right parenthesis at the end of the nth element out to the end of 
the current expression." 

9.4.7 TO and THRU 

EXTRACT, EMBED, DELETE, REPLACE, and HOVE can be made to operate on several 
contiguous elements, i.e., a segment of a list, by using in their respective 
location specifications the TO or THRU command. 

(9| THRU 9^) does a (LC . 9^), followed by an UP, and then a 

(BI i 92)* thereby grouping the segment into a 
single element, and finally does a 1, making the 
final current expression be that element. 

For example, if the current expression is (A (B (C 0) (E) (F G H) I) OK), 
following (C THRU G), the current expression will be ((C 0) (E) (F G H)). 

(9^ TO 92) Same as THRU except last element not included, 

i.e., after the BI, an (RI 1 -2) is performed. 

If both 9^ and 92 are numbers, and 92 is greater than 9|, then 92 counts from 
the beginning of the current expression, the same as 9|. In other words, if 
the current expression is (A B C D E F G), (3 THRU 5) means (C THRU E) not 
(C THRU G). In this case, the corresponding BI command is (BI 1 d^'^^*!), 

THRU and TO are not very useful commands by themselves; they are intended to be 
used in conjunction with EXTRACT, EMBED, DELETE, REPLACE, and MOVE. After THRU 
and TO have operated, they set an internal editor flag informing the above 
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commands that the element they are operating on is actually a segment, and that 
the extra pair of parentheses should be removed when the ^operation is complete. 

Thus: 



*P 

(PROG (& & ATM IND VAL WORD) (PRINl ft T) (PRINl & T) (SETQ IND &) (SETQ VAL &) 
**COMMENT«* (SETQQ 

*(MOVE (3 THRU 4) TO BEFORE 7) 
ftp 

(PROG (& & ATH IND VAL WORD) (SETQ IND &) (SETQ VAL ft) (PRINl ft T) (PRINl ft T) 
'**COHMENT** 



*P 

(* FAIL RETURN FROM EDITOR. USER SHOULD NOTE THE VALUES OF SOURCEXPR AND 

CURRENTFORM. CURRENTFORM IS THE LAST FORH IN SOURCEXPR WHICH WILL HAVE BEEN 

TRANSLATED, AND IT CAUSED THE ERROR.) 

*( DELETE (USER THRU CURRS)) 

"CURRENTFORM. 

«P 

(* FAIL RETURN FROM EDITOR. CURRENTFORM IS 



*P 

...LP (SELECTO & & ft ft NIL) (SETQ Y ft) OUT (SETQ FLG ft) (RETURN Y)) 

*(MOVE (1 TO OUT) TO N HERE] 

*P 

... OUT (SETQ FLG ft) (RETURN Y) LP (SELECTQ ft ft ft ft NIL) (SETQ Y ft)) 
* 



«PP 

[PROG (RF TEMPi TEMP2) 
(COND 

((NOT (MEMB REMARG LISTING)) 

(SETQ TEMPI (ASSOC REMARG NAMEDREMARKS)) «*COMNENT** 
(SETQ TEMP2 (CADR TEMPI)) 
(GO SKIP)) 
(T «*COMMENT«« 
(SETQ TEMPI REMARG))) 
(NCONCl LISTING REMARG) 
(COND 

((NOT (SETQ TEMP2 (SASSOC 



"(EXTRACT (SETQ THRU CADR) FROM COND) 
*P 

(PROG (RF TEMPI TEMP2) (SETQ TEMPI ft) ••COMMENT** (SETQ TEMP2 ft) 
(NCONCl LISTING REMARG) (COND ft ft 
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TO and THRU can also be used directly with XTR.^^ Thus in the previous example. 
If the current expression had been the COND» e.g. the user had first performed 
F COND» he could have used (XTR (SETQ THRU CAOR)) to perform the extraction. 

(9| TO), THRU) both same as (Oj THRU -1). i.e., from 9 ^ through 

the end of the list. 

Examples: 
«P 

(VALUE (RPLACA DEPRP &) (RPLACO &) (RPLACA VARSWORD &) (RETURN)) 
*(MOVE (2 TO) TO N (♦• PROG)) 
*(N (GO VAR)) 
*P 

(VALUE (GO VAR)) 



*P 

(T **COMMENT** (COND &) **COHNENT** (EDITSHASH CL & &) (COND &)) 
*(-3 (GO REPLACE)) 

*(NOVE (COND TO) TO N t PROG (N REPUCE)) 
«P 

(T *«COMMENT«* (GO REPLACE)) 
*\ P 

(PROG (&) **COMNENT** (COND & & &) (COND ft & &) DELETE (COND ft ft) 
REPLACE (COND ft) **COMNENT** (EOITSNASH CL ft ft) (COND ft)) 



Because XTR involves a location specification while A, 6, :, and NBD do 



not. 
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«pp 

[LAMBDA (CLAUSALA X) 
(PROG (A D) 

(SETO A CLAUSALA) 
LP (COND 

((NULL A) 
(RETURN))) 
(SERCH X A) 
(RUMARK (CDR A)) 
(NOTICECL (CAR A)) 
(SETO A (COR A)) 
(GO LP] 

^(EXTRACT (SERCH THRU NOTS) FROM PROG) 

=NOTICECL 

*P 

(LAMBDA (CLAUSALA X) (SERCH X A) (RUMARK &) (NOTICECL &)) 
«( EMBED (SERCH TO) IN (MAP CLAUSALA (FUNCTION (LAMBDA (A) *] 
«PP 

[LAMBDA (CLAUSALA X) 

(MAP CLAUSALA (FUNCTION (LAMBDA (A) 
(SERCH X A) 
(RUMARK (CDR A)) 
(NOTICECL (CAR A] 



9.4.8 The R Command 

(R X y) replaces all instances of x by ^ in the current 

expression, e.g., (R CAADR CADAR). Generates an 
error if there is not at least one instance. 

The R command operates in conjunction with the search mechanism of the editor. 
The search proceeds as described on page 9.23-25, and x can employ any of the 
patterns on page 9.21-23. Each time x matches an element of the structure, the 
element is replaced by (a copy of) each time x matches a tail of the 
structure, the tail is replaced by (a copy of) 

For example, if the current expression is (A (B C) (B . C)), 

(R C D) will change it to (A (B D) (B . D)), 

(R (... . C) D) to (A (B C) (B . D)), 

(R C (D E)) to (A (B (D E)) (B D E)), and 

(R (... . NIL) D) to (A (B C . D) (B . C) . D). 
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If X is an atom or string containing alt-modes, alt-nodes appearing in x. stand 
for the characters matched by the corresponding alt-mode in x* For example, 
(R FOOS FIES) means for all atoms or strings that begin with FOO, replace the 
characters 'FOO' by 'FIE*.^^ Applied to the list 

(FOO F002 XFOOl), (R FOOS FIES) would produce (FIE FIE2 XFOOl), and 
(R SFOOS SFIES) would produce (FIE FIE2 XFIEl). Similarly, (R SOS SA$) will 
change (LIST (CADR X) (CADDR Y)) to (LIST (CAAR X) (CAAOR)).^ 

The user will be informed of all such alt-mode replacements by a message of the 
form x->y, e.g. CADR->CAAR. 

Note that the S feature can be used to delete or add characters, as well as 
replace them. For example, (R $1 S) will delete the terminating i's from all 
literal atoms and strings. Similarly, if an alt-mode in x does not have a mate 
in Y.* ^be characters matched by the $ are effectively deleted. For example, 
(R $/$ $) will change AND/OR to AND.^^ £ can also be a list containing 
alt-modes, e.g. (R Si (CAR S)| will change FOOl to (CAR FOG), FIEl to 
(CAR FIE). 

If x does not contain alt-modes, S appearing in x refers to the entire 



If X matches a string, it will be replaced by a string. Note that it does 

not matter whether x or ;^ themselves are strings, i.e. 

(R SDS SAS), (R "SOS" SAS)7 (R SOS "SAS«)» and (R "SOS" "SAS") are 

equivalent. Note also that x will never match with a number, i.e. 
(R SI S2) will not change 11 to '12. 



Note that CADDR was not changed to CAAAR, i.e. (R SDS SAS) does not mean 
replace every D with A, but replace the first 0 in every atom or string by 
A. If the user wanted to replace every D by A, he could perform 
(LP (R SDS SAS)). 



However, there is no similar operation for changing AND/OR to OR, since the 
first S in always corresponds to the first S in x* the second $ in 2 to 
the second in x* ate. " 



9.58 



expression matched by x» e.g. (R LONGATON '$) changes LONGATON to 'LONGATOM, 
(R (SETQ X &) (PRINT %)) changes every (SETQ X &) to (PRINT (SETQ X &)).^^ 

Since (R $xS SyS) is a frequently used operation for replacing characters, the 
following command is provided: 

(RC X y) equivalent to (R SxS Sy$) 

R and RC change all instances of x to The commands Rl and RCl are available 
for changing Just one, (i.e. the first) instance of x to 

(Rl X y) find the first instance of x and replace it by 

(RCl X y) (Rl $x$ $y$). 

In addition, while R and RC only operate within the current expression, Rl and 
RCl will continue searching, a la the F command, until they find an instance of 
X* even if the search carries them beyond the current expression. 

(SW n m) switches the iith and mth elements of the current 

expression. 

For example, if the current expression is 

(LIST (CONS (CAR X) (CAR Y)) (CONS (CDR X) (COR Y))), 

(SW 2 3) will modify it to be 

(LIST (CONS (CDR X) (CDR Y)) (CONS (CAR X) (CAR Y))). The relative order of n 
and m is not important, i.e., (SW 3 2) and (SW 2 3) are equivalent. 



If X Is a pattern containing an alt-mode pattern somewhere within it, the 
characters matched by the alt-modes are not available, and for the purposes 
of replacement, the effect is the same as though x did not contain any alt- 
modes. For example, if the user types (R (CAR F$) (PRINT S)), the second S 
will refer to the entire expression matched by (CAR FS). 
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SW uses the generalized NTH command to find the 
nth and mth elements, a la the BI-BO commands. 

Thus in the previous example, (SW CAR COR) would produce the same result. 



9.5 Commands That Print 

PP prettyprints the current expression. 

P prints the current expression as though printlevel 

were set to 2. 

(P m) prints mth element of current expression as though 

printlevel were set to 2. 

(P 0) same as P 

(P n n) prints mth element of current expression as though 

printlevel were set to n. 

(P 0 n) prints current expression as though printlevel 

were set to n. 

7 same as (P 0 100) 

Both (P m) and (P m n) use the generalized NTH command to obtain the 
corresponding element, so that m does not have to be a number, e.g. (P CONO 3) 
will work. PP causes all comments to be printed as **CONMENT>** (see Section 
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14). P and ? print as **COMMENT** only those comments that are (top level) 
elements of the current expression. 

PP* prettyprints current expression, including 

comments. 

PP* is equivalent to PP except that it first resets »*comraent**flg to NIL (see 
Section 14). In fact, it is defined as (RESETVAR **CONHENT**FLG NIL PP), see 
page 9.77. 

PPV prettyprints current expression as a variable, 

i.e. no special treatment for LANBDA, CONO, SETQ, 
etc., or for CLISP. 

PPT prettyprints current expression, printing CLISP 

translations, if any. 

All printing functions print to the teletype, regardless of the primary output 
file. No printing function ever changes the edit chain. All record the 
current edit chain for use by \P, page 9.35. All can be aborted with 
control-E. 



Lower expressions are not really seen by the editor; the printing command 
simply sets printlevel and calls print . 
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9.6 Commands That Evaluate 



E 



OK Iff when typed In, 



68 



causes the editor to call 



llspx giving it the next input as argument. 



09 



Example: *E BREAK(FIE FUN) 
(FIE FUM) 
*E (FOO) 



(FIE BROKEN) 



(E X) 



evaluates x> i«e 



• > 



performs evalCx], and prints 



the result on the teletype. 



(E X T) 



same as (E x) but does not print. 



The (Ex) and (E x T) commands are mainly intended for use by macros and 
subroutine calls to the editor; the user would probably type in a form for 
evaluation using the more convenient format of the (atomic) £ command. 



Example: (13 (6ET0 (QUOTE F(X)))) will replace the 3rd element of the current 
expression with the definition of foo.^^ (I N FOO (CAR FIE)) will attach the 



e.g. (INSERT D BEFORE E) will treat E as a pattern, and search for E. 



lispx is used by evalqt and break for processing teletype inputs. If 
nothing else is typed on the same line, lispx evaluates its argument. 
Otherwise, lispx applies it to the next input. In both cases, lispx prints 
the result. See above example, and Sections 2 and 22. 



The I command sets an internal flag to indicate to the structure 
modification commands Jiot to* copy expression(s) when inserting, replacing, 
or attaching. 



(I C Xj ... x^) 



same as (C y| 



y^) where yj»eval[x^]. 
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value of foo and car of the value of fie to the end of the current expression. 
<I F» FOO T) will search for an expression eg to the value of foo. 

If c is not an aton* c is evaluated also. 

Example: (I (COND ((NULL FLG) (QUOTE -1)) (T l)) FOO), If flfl is NIL, inserts 
the value of foo before the first element of the current expression, otherwise 
replaces the first element by the value of foo . 

is an NLAMBOA, NOSPREAD function (not a command). 
Its value is what the current expression would be 
after executing the edit commands com^ . . . oom^ 
starting from the present edit chain. Generates 
an error if any of com^ thru com^ cause errors. 
The current edit chain is never changed. ' 

Example: (I R (QUOTE X) (## (CONS .. Z))) replaces all X*s in the current 
expression by the first cons containing a Z. 

The I command is not very convenient for computing an entire edit command for 
execution, since it computes the command name and its arguments separately. 
Also, the I command cannot be used to compute an atomic command. The following 
two commands provide more general ways of computing commands. 

(CONS X| ... x^) Each is evaluated and its value is executed as 

a command. 



##[cora| ;coro2; ... ;com^] 



Recall that A, B, INSERT, REPLACE, and CHANGE maKe special checks for ## 
forms in the expressions used for inserting or replacing, and use a copy of 
## form instead (see page 9.43). Thus, (INSERT (##3 2) AFTER 1) is 
equivalent to (I INSERT (COPY (## 3 2)) (QUOTE AFTER) 1). 
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For example, (COMS (COND (X (LIST 1 X)))) will replace the first element of the 
current expression with the value of x if non-NIL, otherwise do nothing/^ 

(COMSQ con^ ... com^) executes com| ... com^, 

CONSQ is mainly useful in conjunction with the CONS command. For example* 
suppose the user wishes to compute an entire list of commands for evaluation, 
as opposed to computing each command one at a time as does the CONS command. 
He would then write (CONS (CONS (QUOTE CONSQ) x)) where x computed the list of 
commands, e.g.. (CONS (CONS (QUOTE CONSQ) (GETP FOO (QUOTE CONNANOS ) ) ) ) . 



9.7 Commands That Test 

(IF x) generates an error unless the value of evalCxJ is 

true, i.e., if eval[x] causes an error or 
eval[x>NIL, IF will cause an error. 

For some editor commands, the occurrence of an error has a well defined 
meaning, i.e., they use errors to branch on, as cond uses NIL and non-NIL. For 
example, an error condition in a location specification nay simply mean "not 
this one, try the next." Thus the location specification 

(IPLUS (E (OR (NUNBERP (## 3)) (ERROR!)) T)) specifies the first IPLUS whose 
second argument is a number. The IF command, by equating NIL to error, 
provides a more natural way of accomplishing the same result. Thus, an 
equivalent location specification is (IPLUS (IF (NUNBERP (## 3)))). 



because NIL as a command is a NOP, see page 9.70. 
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The IF command can also b« usad to salact betwean two altarnata lists of 
commands for execution. 



If eval[x] is true, execute coms^; if eval[x] 

causes an error or is equal to NIL» execute 
cons2 • 

For example, the comroftnd (IF (READP T) NIL (P)) will priiit the current 
expression provided the input buffer is empty. 

IF can also be written as: 

(IF x coms^) if evalCx] is true, execute conS|; otherwise 

generate an error. 

(LP . coms) repeatedly executes corns , a list of commands, 

until an error occurs. 

For example, (LP F PRINT (N T)) will attach a T at the end of every print 
expression. (LP F PRINT (IF (## 3) NIL ((N T)))) will attach a T at the end of 
each print expression which does hot already have a second argument.^ 

When an error occurs, LP prints n OCCURRENCES. 



(IF X coms I corns.) 
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Thus IF is equivalent to (COMS (CONS (QUOTE COMSQ) (CONO 
((CAR (NLSETQ (EVAL X))) CONSl) 
(T C0MS2)))). 

i.e. the form (## 3) will cause an error if the edit command 3 causes an 
error, thereby selecting ((N T)) as the list of commands to be executed. 
The IF could also be written as (IF (CDDR (##)) MIL ((N T))), 
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whore n is the number of times corns was 
successfully executed. The edit chain is left as 
of the last complete successful execution of corns . 

(LPQ . cons) same as LP but does not print the message 

n OCCURRENCES. 

In order to prevent non-terminating loops, both LP and LPQ terminate when the 
number of iterations reaches maxloop . initially set to 30. - Since the edit 
chain is left as of the last successful completion of the loop, the user can 
simply continue the LP command with REDO (Section 22). 

(SHOW . x) X a list of patterns. SHOW does a LPQ printing 

all instances of the indicated expression(s), 
e.g. (SHOW FOO (SETQ FIE &)) will print all FOO's 
and all (SETQ FIE &)*s. Generates an error if 
there aren't any instances of the expression(s) . 

(EXAM . x) like SHOW except calls the editor recursively 

(via the TTY: command described on page 9.70) on 
each instance of the indicated espression(s) so 
that the user can examine and/or change them. 

(ORR coroS| ... comS|^) ORR begins by executing coms^, a list of commands. 

If no error occurs, ORR is finished. Otherwise, 
ORR restores the edit chain to its original value, 
and continues by executing coms2, etc. If none of 
the command lists execute without errors, i.e., 



maxloop can also be set to NIL, which is equivalent to infinity. 



9.66 



the QRR "drops off the end", ORR generates an 
error. Otherwise, the edit chain is left as of 
the conpletion of the first conoand list which 
executes without an error. 

For example, (ORR (NX) (!NX) NIL) will perfom a NX, if possible, otherwise a 
!NX, if possible, otherwise do nothing. Sinilarly, DELETE could be written as 
(ORR (UP (1)) (BK UP (2)) (UP (: NIL))). 



9.8 Macros 

Many of the more sophisticated branching commands in the editor, such as ORR, 
IF, etc., are most often used in conjunction with edit macros. The macro 
feature permits the user to define new commands and thereby expand the editor's 

77 

repertoire.' ' Macros are defined by using the M command. 



78 

(M c . coms) For c an atom, M defines c as an atomic command. 

Executing c is then the same as executing the list 
of commands coms. 



For example, (N BP BK UP P) will define BP as an atomic command which does 
three things, a BK, and UP, and a P. Macros can use commands defined by macros 



76 
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NIL as a command list is perfectly legal, and will always execute 
successfully. Thus, malcing the last 'argument' to ORR be NIL will insure 
that the ORR never causes an error. Any other atom is treated as (atom). 
I.e., the above example could be written as (OR NX INX NIL). 

However built in commands always take precedence over macros, i.e., the 
editor's repertoire can be expanded, but not redefined. 

If a macro is redefined, its new definition replaces its old. 
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as well as built in commands in their definitions. For example, suppose Z is 

defined by (N Z -1 (IF (REAOP T) NIL (P))), i.e. Z does a -1, and then if 

nothing has been typed, a P. Now we can define ZZ by 
(N ZZ -1 Z), and ZZZ by (N III »1 -1 Z) or (N ZZZ -1 ZZ). 

Macros can also define list connands, i.e., commands that take arguments. 

(M (c) (arg^ ... arg^^) . corns) c an atom. H defines c as a list command. 

Executing (c e^ ... e,^) is then performed by 
substituting e^ for arg^, ... e^ for ^^^^^ 
throughout corns, and then executing corns. 

For example, we could define a more general BP by (M (BP) (N) (BK N) UP P). 
Thus, (BP 3) would perform (BK 3i), followed by an UP, followed by a P. 

A list command can be defined via a macro so as to take a fixed or indefinite 
number of 'arguments*, as with spread vs. nospread functions. The form given 
above specified a macro with a fixed number of arguments, as indicated by its 
argument list. If the 'argument list* is atomic, the command takes an 
indefinite number of arguments. 

(N (c) arg . corns) c, arg both atoms, defines c as a list comnand. 

Executing (c e^ ... e^) is performed by 
substituting (e^ ... e^), i.e., cdr of the 
command, for arg throughout corns, and then 
executing corns. 

For example, the command 2N0, page 9.30, can be defined as a macro by 
(M (2ND) X (ORR ((LC . X) (LC . X)))). 



Note parallelism to EXPR*s and EXPR**s. 
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Note that for all editor commands, 'built in' commands as well as commands 
defined by macros, atomic definitions and list definitions are completelu 
Independent. In other words, the existence of an atomic definition for c in no 
way affects the treatment of c when it appears as car of a list command, and 
the existence of a list definition for c in no way affects the treatment of c 
when it appears as an atom. In particular, c can be used as the name of either 
an atomic command, or a list command, or both. In the latter case, two 
entirely different definitions can be used. 

Note also that once c is defined as an atomic command via a macro definition, 
it will not be searched for when used in a location specification,, unless it is 
preceded by an F. Thus (INSERT BEFORE BP) would not search for BP, but 
instead perform a BK, and UP, and a P, and then do the insertion. The 
corresponding also holds true for list commands. 



Occasionally, the user will want to employ the S command in a macro to save 
some temporary result. For example, the SW command could be defined as: 

(N (SW) (N H) (NTH N) (S FOO 1) HARK 0 (NTH M) (S FIE 1) 
(I 1 FOO) (I 1 FIE)) 

Since this version of SW sets foo and fie, using SW may have undesirable side 
effects, especially when the editor was called from deep in a computation, we 
would have to be careful to make up unique names for dummy variables used in 
edit macros, which is bothersome. Furthermore, it would be impossible to 
define a command that called itself recursively while setting free variables. 
The BIND command solves both problems. 



A more elegant definition would be: 

(N (SW) (N M) (NTH N) NARK 0 (NTH N) (S FIE 1) (I 1 (## «- 1)) 
«-«- (I 1 FIE)), but this would still use one free variable. 
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(BIND . cons) binds three dummy variables #1, #2* #3, 

(initialized to NIL), and then executes the edit 
commands corns . Note that these bindings are only 
in effect while the commands are being executed, 
and that BIND can be used recursively; it will 
rebind #1, #2, and #3 each time it is invoked. ' 

Thus we could now write SW safely as: 

(N (SW (N N) (BIND (NTH N) (S #1 1) NARK 0 (NTH H) (S #2 1) 

(I 1 #1) ^ (I 1 #2)))). 

User macros are stored on a lisit usermacros . The prettydef command USERNACROS 
(Section 14), is available for dumping all or selected user macros. 

9.9 Miscellaneous Commands 

NIL unless preceded by F or BF, is always a NOP. Thus 

extra right parentheses or square brackets at the 
ends of commands are ignored. 

TTY: calls the editor recursively. The user can then 

type in commands, and have them executed. The 
TTY: command is completed when the user exits from 
the lower editor, (see OK and STOP below). 

The TTY: command is extremely useful. It enables the user to set up a complex 
operation, and perform interactive attention-changing commands part way through 



BIND is implemented by (PROG (#1 #2 #3) (EDITCONS (CDR COM))) where com 
corresponds to the BIND command, and editcoros is an internal editor 
function which executes a list of commands. 
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it. For example the command (MOVE 3 TO AFTER COND 3 P TTY:) allows the user to 
interact, in effect, within the MOVE command. Thus he can verify for himself 
that the correct location has been found, or complete the specification "by 
hand." In effect, TTY: says "I'll tell you what you should do when you get 
there." 

The TTY: command operates by printing TTY: and then calling the editor. The 
initial edit chain in the lower editor is the one that existed in the higher 
editor at the time the TTY: command was entered. Until the user exits from the 
lower editor, any attention changing commands he executes only affect the lower 
editor's edit chain.^^ Vfhen the TTY: command finishes, the lower editor's edit 
chain becomes the edit chain of the higher editor. 

OK exits from the editor 

STOP exits from the editor with an error. Mainly for 

use in conjunction with TTY: commands that the 
user wants to abort. 

Since all of the commands in the editor are errorset protected, the user must 
exit from the editor via a command."*' STOP provides a way of distinguishing 
between a successful and unsuccessful (from the user's standpoint) editing 
session. For example, if the user is executing (MOVE 3 TO AFTER COND TTY:), 
and he exits from the lower editor with an OK, the MOVE command will then 



Of course, if the user performs any structure modification commands while 
under a TTY: command, these will modify the structure in both editors, 
since it is the same structure. 



Or by typing a control-0. STOP is preferred even if the user is editing at 
the evalqt level, as it will perform the necessary 'wrapup' to insure that 
the changes made while editing will be undoable (see Section 22). 
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complete its operation. If the user wants to abort the MOVE command, he must 
make the TTY: command generate an error. He does this by exiting from the 
lower editor with a STOP command. In this case, the higher editor's edit chain 
will not be changed by the TTY: conmand. 



SAVE exits from the editor and saves the 'state of the 



edit' on the property list of the function or 
variable being edited under the property 
EDIT-SAVE. If the editor is called again on the 
same structure, the editing is effectively 
"continued," i.e., the edit chain, nark list, 
value of unfind and undolst are restored. 



For example: 

«P 

(NULL X) 

«F COND P 

(COND (& &) (T &)) 

•SAVE 

FOO 



-EDITF(FOO) 

EDIT 

*P 

(COND (& &) (T &)) 

*\ P 
(NULL X) 
* 



SAVE is necessary only if the user is editing many different expressions; an 
exit from the editor via OK always saves the state of the edit of that call to 
the editor. Whenever the editor is entered, it checks to see if it is editing 
the same expression as the last one edited. In this case, it restores the mark 



on the property list of the atom EDIT, under the property name LASTVALUE. 
OK also remprops EOIT-SAVE from the property list of the function or 
variable being edited. 
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list, th« undolst, and sets unfind to bt tht tdit chain as of tho previous oxit 
from the editor. For example: 



-EDITF(FOO) 

EDIT 

«P 

(LANBDA (X) (PROG & & LP Ic Ir * &)) 



np 

(COND & &) 

*0K 

FOO 

any number of lispx inputs 
except for calls to the editor 

♦•EOITF(FOO) 

EDIT 

*P 

(LAMBDA (X) (PROG & Ic LP & li * &)) 

*\ P 

(COND & &) 



Furthermore, as a result of the history feature (section 22), if the editor is 
called on the same expression within a certain number of lispx inputs, the 
state of the edit of that expression is restored, regardless of how many other 
expressions may have been edited in the meantime. 



Namely, the size of the history list, initially 30, but it can be increased 
by the user. 
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For example: 

♦•EOITF(FOO) 
EDIT 



(COND (& &) (ft ft) (ft) (T ft)) 
FOO 

less than 30 llspx inputs* includina editing 



•-EDITF(FOO) 

EDIT 

"\ P 

(COND (ft ft) (ft ft) (ft) (T ft)) 



Thus the user can always continue editing, including undoing changes from a 
previous editing session, if 



(1) No other expressions have been edited since that session or 

(2) That session was '^sufficiently' recent; or 

(3) It was ended with a SAVE comniand. 



ft « * 



RAISE is an edit macro defined as UP followed by 

(I 1 (U-CASE (## i))). i.e. it raises to upper- 
case the current expression, or if a tail» the 
first element of the current expression* 



LOWER Similar to RAISE, except uses 1-case . 



Since saving takes place at exit time, intervening calls that were aborted 
via control-D or exited via STOP will not affect the editor's memory of 
this last session. 
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CAP 



First does a RAISE, and then lowers all but the 
first character, i.e. the first character is left 
capitalized. 



il^otet RAISE, LCMEU, and CAP ere ot( MOPs if the cor res ponding atom or string is 
already in that state, 

(RAISE x) equivalent to (I R (L-CASE x) x), i.e. changes 

every lower-case x to upper-case in the current 
expression. 

(LOWER x) similar to RAISE, except perfonns (I R x (L- 

CASE X)). 



Note in both (RAISE x) and (LOWER x), x is typed in in upper case. 



REPACK Permits the 'editing' of an atom or string. 

For example: 



*P 

... "THIS IS A L06N STRING") 

REPACK 

*EDIT 

P 

(THISX ISX AX LOGNX STRING) 
«(SW G N) 

"THIS IS A LONG STRING" 



REPACK operates by calling the editor recursively on unpack of the current 



Note that this could also have been accomplished by (R SGNS SNGS) or simply 
(RC GN NG). 
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expression, or if it is a list, on unpack of its first element. If the lower 
editor is exited successfully, i.e. via OK as opposed to STOP, the list of 
atoms is made into a single atom or string, which replaces the atom or string 
being 'repacked.* The nevr atom or string is always printed. 

(REPACK 9) does (LC 9) followed by REPACK, e.g. 

(REPACK THISS). 

( ; . x) X is the text of a comment. ; ascends the edit 

chain looking for a 'safe' place to insert the 

coinroent, e.g., in a cond clause, after a prog 

statement, etc., and inserts (* . x) after that 

point, if possible, otherwise before. For 

exiunple, if the current expression is 

(FACT (SUBl N)) in 

[COND 

((ZEROP N) 1) 
(T (ITIHES N (FACT (SUBl N] 

(; CALL FACT RECURSIVELY) would insert 

(* CALL FACT RECURSIVELY) before the itimes 

expression." 

; does not change the edit chain, but unf ind is 
set to where the comment was actually inserted. 

JOINC is used to Join two neighboring CONO's together, 

e.g. (COND dausOf clause^) followed by 



If inserted after the itimes . the comment would then be (incorrectly) 
returned as the value of the cond . However, if the cond was itself a prog 
statement, and hence its value was not being used, the comment could be 
(and would be) inserted after the itimes expression. 
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(COND clause^ clause^) becQmes 
(COND claus«| clause2 clause^ clause^). JOINC 
does an (F COND T) first so that you don't have to 
be at the first COND. 



(SPtlTC x) 



splits one COND into two. x specifies the last 
clause in the first COND, e.g. (SPLITC 3) splits 
(COND clause J clause2 clause^ clause^) into 
(COND clause J clause^) (COND clause^ clause^). 
Uses generalized NTH comoiand, so that x does not 
have to be a number, e.g., the user can say 
(SPLITC RETURN), neaning split after the clause 
containing RETURN. SPLITC also does an (F CONO T) 
first. 



CL 



Clispifies current expression. See Section 23. 



OW 



Dwinifies current expression. See Section 17 and 
23. 



(RESETVAR var fona . corns) executes corns while var is reset to the value of 

form , and then restores var, i.e. effectively 
calls the function resetvar (Section 5). 
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9.10 UNDO 



Each command that causes structure modification automatically adds an entry to 
the front of undolst that contains the infomation required to restore all 
pointers that were changed by that command. 

UNDO undoes the last» i.e. most recent, structure 

modification command that has not yet been 

on 

undone, and prints the name of that command, 
e.g., NBD UNDONE. The edit chain is then exactly 
what it was before the 'undone' command had been 
performed.^^ If there are no connands to undo, 
UNDO types NOTHING SAVED. 

I UNDO undoes all modifications performed during this 

editing session, i.e. this call to the editor. 
As each command is undone, its name is printed a 
la UNDO. If there is nothing to be undone, lUNOO 
prints NOTHING SAVED. 



Since UNDO and fUNDO cause structure modification, they also add an entry 
to undolst . However, UNDO and !UNDO entries are skipped by UNDO, e.g., if 
the user performs an INSERT, and then an MBD, the first UNDO will undo the 
MBD, and the second will undo the INSERT. However, the user can also 
specify precisely which commands he wants undone by Identifying the 
corresponding entry on the history list as described in Section 22. In 
this case, he can undo an UNDO command, e.g. by typing UNDO UNDO, or undo a 
!UNDO command, or undo a command other than that most recently performed. 



Undoing an event containing an I, E, or S command will also undo the side 
effects of the evaluation(s), e.g. undoing (I 3 (/NCONC FOO FIE)) will not 
only restore the 3rd element but also restore FOO. Similarly, undoing an S 
command will undo the set. See discussion of UNDO in Section 22. (Note 
that if the I command was typed directly to the editor, /NCONC would 
automatically be substituted for NCONC as described in Section 22.) 
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Whenever the user continues an editing session as described on page 9.72-74, 
the undo infornation of the previous session is protected by inserting a 
special blip, called an undo-blocli, on the front of undolst . This undo-block 
will terminate the operation of a lUNOO, thereby confining its effect to the 
current session, and will sinilarly prevent an UNDO command from operating on 
comMands executed in the previous session. 

Thus, if the user enters the editor continuing a session, and inoiediately 
executes an UNDO or !UNDO, the editor will type BLOCKED instead of 
NOTHING SAVED. Sinilarly, if the user executes several conmands and then undoes 
them all, another UNDO or fUNDO will also cause BLOCKED to be typed. 

UNBLOCK removes an undo-block. If executed at a non- 

blocked state, i.e. if UNDO or lUNDO coul4 
operate, types NOT BLOCKED. 

TEST adds an undo-block at the front of undolst . 

Note that TEST together with I UNDO provide a 'tentative' mode for editing, i.e. 
the user can perform a number of changes, and then undo all of them with a 
single fUNOO command. 
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9.11 Edltdefault 



Whenever a command is not recojjnized, i.e.. Is not 'built in' or defined as a 
macro, the editor calls an internal function, editdefault , to determine what 
action to take.^' If a location specification is bding /executed; an internal 
flag informs editdefault to treat the command as though it had been preceded by 
an F. 

If the command is a list, an attempt is made to perform spelling correction on 
car of the command^'^ using editcomsl , a list of all list edit commands. If 
spelling correction is successful, the correct command name is' rplaca ed into 
the command, and the editor continues by executing the command. 
In other words, if the user types (LP F PRINT (HB60 AND (NULL FLG))), only one 
spelling correction will be necessary to change MB60 to NBO. If spelling 
correction is not successful, an error is generated. 

If the command is atomic, the procedure followed is a little more elaborate. 
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Since editdefault Is part of the edit block, the user cannot advise or 
redefine It as a means of augmenting or extending the editor. However, the 
user can accomplish this via edituserfn . If the value of the variable 
edituserfn is T, editdefault calls the function edituserfn giving it the 
command as an argument. If edituserfn returns a non-NIL value, its value 
is interpreted as a single command and executed. Otherwise, the error 
correction procedure described below is performed. 

unless dwimflg gNIL. See Section 17 for discussion of spelling correction. 

When a macro Is defined via the M command, the command name is added to 
edltcomsa or editcomsl , depending on whether it is an atomic or list 
command. The prettydef command USERMACROS (Section 14), is aware of this, 
and provides for restoring edltcomsa and editcomsl . 

Throughout this discussion, if the command was not typed in directly, the 
user will be asked to approve the spelling correction. See Section 17. 
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1) If the command is one of the list commands, i.e., a member of edit corns I . 
and there is additional input on the same teletype line, treat the entire 
line as a single list command. Thus, the user may omit parentheses for 
any list command typed in at the top level (provided the command is not 
also an atomic command, e.g. NX, 6K). For example, 

*P 

(COND (& &) (T &)) 
«XTR 3 23 

"MOVE TO AFTER LP 

« , 

If the command is on the list editcomsl but no additional input is on the 
teletype line, an error is generated, e.g. 

*P 

(COND (& &) (T &)) 
•MOVE 

MOVE? 
« 

If the command is on editcomsl , and not typed in directly, e.g. it appears 
as one of the commands in a LP command, the procedure is similar, with the 
rest of the command stream at that level, being treated as 
"the teletype line", e.g. 

(LP F (COND (T &)) XTR 2 2).^^ 
Z) If the command was typed in and the first character in the command is an 8, 



The line is read using readline (Section 14). Thus the line can be 
terminated by a square bracket, or by a carriage return not preceded by a 
space. 



Note that if the command is being executed in location context, editdefault 
does not get this far, e.g. (MOVE TO AFTER COND XTR 3) will search for XTR, 
not execute it. However, (MOVE TO AFTER COND (XTR 3)) will work. 
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treat the 8 as a mistyped left parenthesis, and and the rest of the line as 
the arguments to the command, e.g., 



«P 

(COND (& &) (T &)) 
*8-2 (Y (RETURN Z))) 

= (-2 
«P 

(COND (Y &) (& &) (T &)) 



3) If the command was typed in, is the name of a function, and is followed by 
NIL or a list car of which is not an edit command, assume the user forgot 
to type E and means to apply the function to its arguments, type *E and the 
function name, and perform the indicated computation, e.g. 

*BREAK(FOO) 
»E BREAK 
(FOO) 

4) If the last character in the command is P, and the first n-1 characters 
comprise a number, assume that the user intended two commands, e.g., 

«P 

(COND (& &) (T &)) 

«0P 

«0 P 

(SETQ X (COND & ft)) 



07 

5) Attempt spelling correction using editcomsa, and if successful,*^ execute 
the corrected command. 



6) Otherwise, if there is additional input on the same line, or command 
stream, spelling correct using edltcorosl, e.g.. 



07 

See footnote on page 9.81. 



9.82 



*M6B0 SETQ X 

:=MBO 



7) Otherwise, generate an error < 



9.12 Editor Functions 



odlteC expr ; coins ;atiiii) 



edits an expression. Its value is the last 
element of editUlist[ expr]; cons jatn]. Generates 
an error if expr is not a list. 



editlC 1 ; corns ; atm ;mess ] 



Oft 

editl 13 the editor. Its first argument is the 
edit chain, and its value is an edit chain, namely 
the value of 1 at the time edltl is exited. 



corns is an optional list of commands. For 
Interactive editing, coms is NIL. In this case, 
editl types EDIT and then waits for input from 
teletype. Exit occurs only via an OK, STOP, or 
SAVE command. 



If coms is not NIL, no message is typed, and each 
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edit-eU, not edit-one. 

1 is a specvar , and so can be examined or set by edit commands. For 
example, t is equivalent to (E (SETQ L (LAST L)) T). However, the user 
should only manipulate or examine 1 directly as a last resort, and then 
with caution. 

If mess Is not NIL, editl types it instead of EDIT. For example, the TTY: 
conmand is essentially (SETQ L (EDITL L NIL NIL (QUOTE TTY:))). 
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member of corns is treated as a command and 
executed. If an error occurs in the execution of 
one of the commands, no error message is printed, 
the rest of the commands are ignored, and edit! 
exits with an error, i.e. the effect is the same 
as though a STOP command had been executed. If 
all commands execute successfully, editl returns 
the current value of 1. 

atm is optional. On calls from editf . it is the 
name of the function being edited; on calls from 
editv , the name of the variable, and calls from 
editPt the atom whose property list is being 
edited. The property list of atm is used by the 
SAVE command for saving the state of the edit. 
Thus SAVE will not save anything if atro«WIL. i.e. 
when editing arbitrary expressions via edite or 
editl directly. 

editlOCl;coms:roess;editlflg]^^^ like editl except does not rebind or 

initialize the editor's various state variables, 
such as lastail . unfind, undolst, marklst . etc. 

editfCx] nliunbda, nospread function for edit ing a function. 

car[x] is the name of the function, cdrCx] an 
optional list of commands. For the rest of the 
discussion, fn is car[x], and coms is cdrCxj* 

The value of editf is fn. 



editlflfl«T is for internal use by the editor. 
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(1) In the most common case, fn is an expr, and editf simply performs 
pu td[ f n ; edi te[ getd[ f n ] ; coms ; f n ] ] . 



(2) If fn is not an expr, but has an EXPR property, editf prints PROP, and 
performs edite[getp[fn;EXPR];comsifn]. If edlte returns (i.e. if the 
editing is not terminated by a STOP), and some changes were made, editf 
performs unsavedefCfn], prints UNSAVED, and then does putdCfn;value-of- 
edite]. 

(3) If fn is neither an expr nor has an EXPR property, but its top level value 
is a list, editf assumes the user meant to call editv , prints ^EOITV, calls 
editv and returns. Similarly, if fn has a non-NIL property list, editf 
prints "EOITP, calls editp and returns. 

(4) If fn is neither a function, nor has an EXPR property, nor a top level 
value that is a list, nor a non-NIL property list, editf attempts spelling 
correction using the spelling list userwords, and if successful, goes 
back to (1). 

Otherwise, editf generates an fn NOT EDITABLE error. 

If editf ultimately succeeds in finding a function to edit, i.e. does not exit 
by calling editv or editp , editf calls the function addspell after editing has 
been completed. Addspell 'notices' fn, i.e. sets lastword to fn, and adds fn 
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Unless dwimf lg =NIL. Spelling correction is performed using the function 
misspelled? . If fnsNIL, misspelled? returns the last 'word* referenced, 
e.g. by deflneg, editf , prettyprint etc. Thus if the user defines foo and 
then types editf[], the editor will assume he meant foo , type *F00, and 
then type EDIT. See Section 17. 

Unless dwimf Ig aNIL. addspell is described in Section 17. 
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to the appropriate spelling lists. If any changes were roade, editf also calls 
newf lie? , which performs the updating for the file package as described in 

Section 14. 

editvCeditvx] nlambda, nospread function, similar to editf . for 

edit ing values. car[editvx] specifies the value, 
cdr[editvx] is an optional list of commands. 

If car[editvx] is a list, it ]ls evaluated and its value given to edite , e.g. 
EDITV((CDR (ASSOC (QUOTE FOO) DICTIONARY)))). In this case, the value of editv 
is T. 

However, for most applications, car[editvx] is a variable name, i.e. atomic, as 
in EOITV(FOO). If the value of this variable is NOBIND, editv checks to see if 
it is the name of a function, and if so, assumes the user meant to call editf, 
prints bEDITF, calls editf and returns. Otherwise, editv attempts spelling 
correction using the list userwords ."^^^ Then editv will call edite on the value 
of car[editvx] (or the corrected spelling thereof). Thus, if the value of foo 
is NIL, and the user performs (EOITV FOO), no spelling correction will occur, 
since foo is the name of a variable in the user's system, i.e. it has a value. 
However,, edite will generate an error, since foo's value is not a list, and 
hence not editable. If the user performs (EDITV FOOD), where the value of fooo 
is NOBIND, and foo is on the user's spelling list, the spelling corrector will 
correct FOOO to FOO. Then edite will be called on the value of foo. Note that 
this may still result in an error if the value of foo is not a list. 

When (if) edite returns, editv sets the variable to the value returned, and 
calls addspell and newfile? . 



Unless dwimflg =WIL. Misspelled? is also called if carCeditvx] is NIL, so 
that EDITVO will edit lastword. 
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The value of edltv Is the name of the variable whose value was edited. 



editptx] . nlambda, nospread function » similar to editf for 

edit ing property lists. If the property list of 
car[x] is NIL» editp attempts spelling correction 
using userwords . Then editp calls edite on the 
property list of car[x]» (or the corrected 
spelling thereof). Vftien (if) edite returns* editp 
rplacd 's car[x] with the value returned, and calls 
addspell . 

The value of editp is the atom whose property list 
was edited. 

editf nsCx] nlambda, nospread function, used to perform the 

same editing operations on several functions. 
car[x] is evaluated to obtain a list of functions. 
cdr[x] is a list of edit commands, editfns maps 
down the list of functions, prints the name of 
each function, and calls the editor (via editf ) on 
that f unction, 

For example, E0ITFNS(FOOFNS (R FIE FUH)) will change every FIE to FUN in each 
of the functions on f oof ns . 

The call to the editor is errorset protected, so 



i.e. the definition of editfns might be: 

[HAPC (EVAL (CAR X)) (FUNCTION (LANBDA (Y) 
(APPLY (QUOTE EDITF) 

(CONS (PRINT Y T) (CDR X] 
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that if the editing of one function causes an 
error, editfns will proceed to the next 
f unction. ■'^^ 



Thus in the above example, if one of the functions did not contain a FIE, the R 
command would cause an error, but editing would continue with the next 
function. 



The value of editfns is NIL. 

edit4e[pat;x;changeflg] is the pattern natch routine. Its value is T if 

£at-matches x* See page 9.21-23 for definition of 
•match '.^^'^ 



Note: before each search operation in the editor begins, the entire pattern is 
scanned for atoms or strings containing alt-modes. These are replaced by 
patterns of the form (CONS (QUOTES) (UNPACK atom/string)) for 6a, and 
(CONS (QUOTE SS) (CONS (NCHARS atom/string) (UNPACK atom/string))), for 6b. 
Thus from the standpoint of ecliMe, pattern type 6a is indicated by carCpat] 
being the atom S ($ is alt-mode) and pattern type 6b by car[pat] being the atom 
S$ (double alt-mode). 



In particular, if an error occurred while editing a function via its EXPR 
property, the function would not be unsaved. In other words, in the above 
example, only those functions which contained a FIE, i.e. only those 
actually changed, would be unsaved. 

^^'^ changef Ig is for internal use by the editor. 

In latter case, atom/string corresponds to the atom or string up to but not 
including the final two-alt -modes. In both cases, dunpack is used wherever 

possible. 
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Therefore, if the user wishes to call edit4e directly, he must first convert 
any patterns which contain atoms or strings ending in alt-modes to the form 
recognized by edit4e. This is done with the function editfpat . 



editfpat[pat;f Ig] 



makes a copy of £at with all patterns of type 6 



converted to the form expected by edit4e. 
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editf indp[ X ; pat ; fig] 



allows a program to use the edit find command as a 
pure predicate from outside the editor, x is an 
expression, £at a pattern. The value of editf indp 
is T if the command F pat would succeed, NIL 
otherwise, editfindp calls editfpat to convert 
pat to the form expected by edit4e, unless f lg «T. 
Thus, if the program is applying editfindp to 
several different expressions using the same 
pattern, it will be more efficient to call 
editfpat once, and then call editfindp with the 
converted pattern and f lg «T. 



esubst[x;y;z;errorflg;charflg] equivalent to performing (R y x)^'^ with z as 

the current expression, i.e. the order of 
arguments is the same as for subst . Note that x 
and/or x can employ alt-modes. The value of 
esubst is the modified z. Generates an error^^^ 



10Q 

f lg =T is used for internal use by the editor. 

unless charflgsT, in which case it is equivalent to (RC y x). See page 
9.59. 

Hi 

of the type that never causes a break. 
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if ^ not found in z. If errorflfl «T, also prints 
an error message of the ford y ? . 

esubst is always undoable. 

changenane[fn;froni;to] replaces all occurrences of from by to, in the 

definition of fn. If fn is an expr, changename 
performs nlsetq[esubst[to;from;gettltfn]]]. If fn 
is compiled t changename searches the literals of 
fn (and all of its compiler generated 
subfunctions), replacing each occurrence of from 
with to.^^^ 

The value of changename is fii if at least one 
Instance of from was found* otherwise NIL. 

changename is used by break and advise for changing calls to fnl to calls to 
fnl-IN-fnZ . 

editracefn[com] is available to help the user debug complex edit 

macros, or subroutine calls to the editor. If 
editracefn is set to T, the function editracefn is 
called whenever a command that was not typed in by 
the user is about to be executed, giving it that 
convAand as its argument. However, the TRACE and 
BRE/UC options described below are probably 
sufficient for most applications. 
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Will succeed even if from in called from fn via a linked call. In this 
case» the call will also be relinked to call to instead. 
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edltracefn is set to TRACE, the nane of the 
conmand and the current expression are printed. 
If editracefns BREAK, the sane information is 
printed, and the editor goes into a break. The 
user can then examine the state of the editor. 

editracefn is initially HtL. 
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Numbers 

(A el ... em) (edit command) 9.13,39-40 

ADDSRELL[ X ; SPLST ; N ] * 9 .85-87 
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(BI n m) (edit command) 9.8,52 

(BI n) (edit command) 9.52 
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BK (edit command) 9.10,18-19 
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BLOCKED (typed by editor) 9.79 
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commands that move parentheses (in editor) 9.51-54 
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continuing an edit session 9.72-74 

control-D 9.71 

control-E 9.3 

current expression (in editor) 9.2,4,8,11-15,23 

DELETE (edit command) 9.14,37,40,42 

(DELETE . @) (edit command) 9.42 

DESTINATION IS INSIDE EXPRESSION BEING MOVED 

(typed by editor) 9.49 

DW (edit command) 9.77 

DWIMFLG (system variable/parameter) 9.80,85-86 

E (edit command) 9.9,62 

(E X T) (edit command) 9.62 

(E x) (edit command) 9.62 

EDIT (typed by editor) 9.83 

edit chain 9.4,7,11-13,15,23 

edit commands that search 9.21-33 

edit commands that test 9.64 

edit macros 9.67-70 

EDIT-SAVE (property name) 9.72 

E0IT4E[PAT;X;CHANGEFLG] i 9.88 

EDITCOMSA (editor variable/parameter) 9.80,82 

EDITCOMSL (editor variable/parameter) 9.80-82 

EDITDEFAULT (in editor) 9.80-83 

EDITECEXPR; COMS; ATM] 9.1,83,86-87 

EDITF[X] NIL* 9.1,84-86 

EDITFINDP[X;PAT;FLG] 9.89 

EDITFNSCX] NL» 9.87-88 

E0ITFPAT[PAT;FL6] 9.89 

editing compiled functions 9.90 
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EDITL[L;C0MS;ATM;MESS3 9.83-84 

EDITLOtL;COMS;MESS;EOITLFL63 9.84 

EOITPCX] NL* 9.1,85.87 

E0ITQUIETFL6 (editor variable/parameter) 9. 22 

EOITRACEFN 9.90-91 

EDITUSERFN 9.80 

EDITVtEDITVX] NL« 9.1,85-86 

(EMBED 0 IN ...) (edit command) 9.48 

errors (in editor) 9.3 

ESUBSTC X ; Y ; Z ; ERR0RFL6 ; CHARFL6 ] 9 . 89 

(EXAM . x) (edit command) 9.66 

EXPR (property name) 9.85,88 

(EXTRACT @1 from . 92) (edit coninand) 9.46 

F (edit command) 9.6,25-26 

F pattern (edit command) 9.25 

(F pattern N) (edit command) 9.26 

(F pattern n) (n a number, edit command) 9.26 

(F pattern T) (edit command) 9.26 

(F pattern) (edit command) 9.27 

(F>= ...) (edit command) 9.27 

FOR (In INSERT command) (in editor) 9.41 

FROM (in EXTRACT command) (in editor) 9.46 

(FS ...) (edit command) 9.27 

generalized NTH command (in editor) 9.32,52,60 

HERE (in edit command) 9.42 

history list 9.73,78 

(I c xl ... xn) (edit command) 9.62 

(IF X comsl coms2) (edit command) 9.65 

( IF X comsl) (edit command) 9.65 

(IF x) (edit command) 9.64 

implementation of structure modification commands 

(in editor) 9.37-39 

IN (in EMBED command) (in editor) 9.48 

(INSERT ... AFTER . ©) (edit command) 9.41 

(INSERT ... BEFORE . (3) (edit command) 9.41 

(INSERT ... FOR . 9) (edit conmand) 9.41 

JOINC (edit command) 9.76 

L-CASE[X;FL63 9.74 

LASTAIL (editor variable/parameter) 9.16-17,25,84 

LASTVALUE (property name) 9.72 

LASTWORD (system variable/parameter) 9.85-86 

(LC . 9) (edit command) 9.30 

(LCL . @) (edit command) 9.30 

(LI n) (edit command) 9.6,53 

LISPX 9.62,73 

(LO n) (edit command) 9.8,53 

location specification (in editor) 9.28-29,64 

LOCATION UNCERTAIN (typed by editor) 9.17 

LOWER (edit command) 9.74 

(LOWER x) (edit command) 9.75 

(LP . coms) (edit command) 9.65-66 

(LPQ . coms) (edit command) 9.66 

(M (c) (argl ... argn) . corns) (edit command) ... 9.68 

(M (c) arg . corns) 9.68 

(M c . coms) (edit command) 9.67 

macros (in editor) 9.67-70 

MARK (edit command) 9.34 
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(MARK atom) (edit command) 9.34 

MARKLST (editor variable/parameter) 9.34,84 

MAXLEVEL (editor variable/parameter) 9.24,26 

MAXLOOP (editor variable/parameter) 9.66 

MAXLOOP EXCEEDED (typed by editor) 9.66 

(HBD el ... em) (edit command) 9.47 

(MOVE 01 TO com . 02) (edit command) 9.48 

n (n a number, edit command) 9.3,17 

(N el ... em) (edit command) 9.36 

(n el ... em) (n a number, edit command) 9.5,36 

(n) (n a number, edit command) 9.5,36 

NEWFILE?[NAME;VARSFLG] 9.86 

NEX (edit command) 9.32 

(NEX X) (edit command) 9.32 

NIL (edit command) 9.64,70 

NOBIND 9.86 

NOT BLOCKED (typed by editor) 9.79 

NOT CHANGED, SO NOT UNSAVED (typed by editor) ... 9.85 

NOT EDITABLE (error message) 9.83,85 

NOTHING SAVED (typed by editor) 9.78 

(NTH n) (n a number, edit command) 9.20 

(NTH x) (edit command) 9.32-33 

NX (edit command) 9.8,18-19 

(NX n) (n a number, edit command) 9.19 

OCCURRENCES (typed by editor) 9.65 

OK (edit command) 9.71,76,83 

(ORE ...) (edit command) 9.27 

(ORR ...) (edit command) 9.66 

P (edit command) 9.2,60 

(P m n) (edit command) 9.60 

(P m) (edit command) 9.60 

(pattern .. 0) (edit command) 9.33 

pattern match (in editor) 9.21-23,88-89 

PP (edit command) 9.2,60 

PP* (edit command) 9.61 

PPT (edit command) 9.61 

PPV (edit command) 9.61 

prompt character 9.2 

PROP (typed by editor) 9.85 

(R X y) (edit command) 9.7,57 

(Rl X y) (edit command) 9.59 

RAISE (edit command) 9.74 

(RAISE X) (edit command) 9.75 

(RC X y) (edit command) 9.59 

(RCl X y) (edit command) 9.59 

READLINE[LINE;LISPXFLG] 9.81 

REPACK (edit command) 9.75 

(REPACK 0) (edit command) 9.76 

(REPLACE 0 WITH ...) (edit command) 9.42 

RESETVAR[RESETX;RESETY;RESETZ] NL 9.77 

(RESETVAR var form , coms) (edit command) 9.77 

(RI n m) (edit command) 9.8,53 

(RO n) (edit command) 9.8,53 

(S var . 0) (edit command) 9.36 

SAVE (edit command) 9.72,74,83-84 

search algorithm (in editor) 9.23-25 

(SHOW . X) (edit command) 9.66 
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spoiling correction 9.82,86 

(SPLITC X) (edit command) 9.77 

STOP (edit command) 9.71-72*76,83-85 

structure modification commands (in editor) 9.36-60 

(SURROUND @ IN ...) (edit command) 9.48 

(SW n m) (edit command) 9.59-60 

teletype 9.61 

TEST (edit command) 9.79 

THRU (edit command) 9.54-57 

TO (edit command) 9.54-57 

TTY: (edit command) 9.66,70-72 

TTY: (typed by editor) 9.71 

U-CASE[X] 9.74 

UNBLOCK (edit command) 9.79 

UNDO (edit command) 9.10,78 

undoing (in editor) 9.10,36,78-79 

UNDOLST (editor variable/parameter) 9.72,78-79,84 

UNDONE (typed by editor) 9.78 

UNFIND (editor variable/parameter) 9. 25, 35,41-42, 46,48-51» 

72-73,76,84 

UNSAVED (typed by editor) 9.85 

UP (edit command) 9.12,15-16,25,43 

UPFINDFLG (editor variable/parameter) 9.25,28,44 

USERMACROS (editor variable/parameter) 9.70 

USERMACROS (prettydef command) 9.70,80 

USERWORDS (system variable/parameter) 9.85-87 

WITH (in REPLACE command) (in editor) 9.42 

WITH (In SURROUND command) (in editor) 9.48 

(XTR . @) (edit command) 9.45 

0 (edit command) 9.4-5,17 

!0 (edit cormnand) 9.18 

! NX (edit command) 9.19-20 

!UNDO (edit command) 9.78 

##[COMS] NL« 9.29,63 

## (in INSERT, REPLACE, and CHANGE commands) 9.43 

S (alt-mode) (in edit pattern) 9.12,21 

5 (alt-mode, in R command) (in editor) 9.58 

$$ (two alt-modes) (in edit pattern) 9.22 

SBUFS (alt-modeBUFS) (prog, asst, cdmniand) 9.7 

6 (in edit pattern) 9.11,21 

& (typed by editor) 9.2 

* (typed by editor) 9.2 

* (in MBD command) (in editor) 9.47 

«*COMMENT*« (typed by editor) 9.60 

««COMMENT**FLG (prettydef variable/parameter) ... 9.61 

*ANY* (in edit pattern) 9.21 

(in edit pattern) 9.11,22 

-> (typed by editor) 9.58 

-n (n a number, edit command) 9.3,17 

(-n el ... em) (n a number, edit command) 9.5,36 

.. (edit command) 9.33 

— (in edit pattern) 9.22-23 

... (typed by editor) 9.13,15 

(2ND . 9) (edit command) 9.30 

(3RD . @) (edit command) 9.30 

8 (Instead of left parenthesis) 9.82 

(: el ... era) (edit conroand) 9.14,40 
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(; . x) (edit command) 9.76 

= (typed by editor) 9.12 

^- (in edit pattern) 9.22 

=E (typed by editor) 9.82 

=EOITF (typed by editor) 9.86 

=EDITP (typed by editor) 9.85 

=EDITV (typed by editor) 9.85 

? (edit command) 9.2,60 

? (typed by editor) 9.3 

@ (location specification) (In editor) 9.29 

((?! THRU (32) (edit command) 9.54 

(01 THRU) (edit command) 9.56 

(@1 TO 92) (edit command) 9.54 

(01 TO) (edit command) 9.56 

\ (edit command) 9.11,34-35,41 

(\ atom) (edit command) 9.34 

\P (edit command) 9.11,35,61 

t (edit command) 9.4,18 

(edit command) 9.34 

(«- pattern) (edit command) 9.30 

•-^ (edit comnand) 9.34 
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SECTION 10 

ATOM, STRING, ARRAY, AND STORAGE MANIPULATION 



10.1 Pnames and Atom Manipulation 

The term 'print name' (of an atom) in LISP 1.5 referred to the characters that 
were output whenever the atoni was printed. Since these characters were stored 
on the atom's property list under the property PNAHE, pname was used 
interchangeably with * print name*. In INTERLISP, all pointers have pnames , 
although only literal atoms and strings have their pname explicitly stored. 

The pname of a pointer are those characters that are output when the pointer is 
printed using print , 

e.g., the pname of the atom ABCX(o' consists of the five characters ABC(0. The 
pname of the list (A B C) consists of the seven characters (A B C) (two of the 
characters are spaces 

Sometimes we will have occasion to refer to the prin2~pname . 

The prin2' pname are those characters output when the corresponding pointer is 
printed using prin2. 

Thus the prinZ-pname of the atom ABCX(0 is the six characters ABCX(0. Note that 
the pname of numbers depends on the setting of radix. 



% is the escape character. See Sections 2 and 14. 
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pack[x] If X is a list of atoms, the value of pack is a 

single atom whose pname is the concatenation of 
the pnames of the atoms in x, e.g. 
pack[(A BC OEF G)>ABCDEFG. 

If the pname of the value of packCx] is the same 
as that of a number, pack[x] will be that number, 
e.g. pack[(l 3.4)]«13.4, 
pack[(l E -2)]-. 01. 

Although x is usually a list of atoms., it can be a 
list of arbitrary INTERLISP pointers. The value 
of pack is still a single atom whose pname is the 
same as the concatenation of the pnames of all the 
pointers in x» e*9* 

pack[((A B)"CD")] « X(A% BX)CO. 

In other words, mapc[x;prinl] and prinlCpack[x]] 
always produce exactly the same output. In fact, 
pack actually operates by calling print to convert 
the pointers to a stream of characters (without 
printing) and then makes an atom out of the 
result. 

ifotet atoms are restricted to < 99 characters , Attemptitii/ to create a larger 
atom either via pack or ba typing one in (or reading from a file) will 
cause an error, ATOH TOO LONG. 



unpack[x;f Ig] The value of unpack is the pname of x as a list of 

characters ( atoms ),^ e.g. 



There are no special 'character-atoms' in INTERLISP, i.e. an atom 
consisting of a single character is the same as any other atom. 



10.2 



unpack[ABC] > (A B C) 

unpackC"ABC(0"] » (A B C X( 0) 
In other words prinl[x] and inapc£unpack[x];prinl] 
produce the same output. 

If flfl»T, the prinZ-pname of x is used* e.g. 
unpack["ABC(D";T]« (X" A B C X( 0 X"). 



ilTotet unpttck[x] perform n cojises, where n is the number of characters in the 
pname of x, " " 

dunpack[x;scratchllst;flg] a destructive version of unpack that does not 

perform any conses but instead uses scratchlist to 
make a list equal to unpack[x;flg]. If the p-name 
is too long to fit in scratchlist , dunpack calls 
unpack and returns unpack[x;flg]. Gives an error 
if scratchlist is not a list. 

ncharsCx;flg] number of characters in pname of x.^ If flg«T, the 

prln2~pname is used. E.g. ncharsCABC'J-d, 
ncharsC"ABC";T]«5. 

nthchar[x;n;flg] Value is nth character of pname of x- Equivalent 

to carCnth[unpack[x;flg];n]] but faster and does 
no conses . n can be negative » in which case 
counts from end of pname . e.g. -1 refers to the 



Both nthchar and nchars work much faster on objects that actually have an 
internal representation of their pname, i.e. literal atoms and strings, 
than they do on numbers and lists, as they do not have to simulate 
printing. 
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last character, -2 next to last, etc. If n is 
greater than the number of characters in the 
pnaiae, or less than minus that number, or 0, the 
value of nthchar is NIL. 



packc[x] 



like pack except x is a list of (ASCII) character 
codes, e.g. packc[(70 79 79)]«FOO. 



chcon[x;flg] 



lik» unpack , except returns the pnaroe of x as a 

list of (ASCII) character codes, e.g. 

chcon[FOO] > (70 79 79). If flg«T. the prinZ-pname 
is used. 



chconlCx] 



returns character code of first character of pname 
of X, e.g. chconl[FOO] = 70. Thus chconCx] could 
be «fritten as roapcar[unpack[x];chconl]. 



dchcon[x;scratchlist;flg] similar to dunpack 



character[n] 



n is an ASCII character code. Value is the atom 
having the corresponding single character as its 
pname , ^ e.g. character[ 70 ] « F. Thus, unpack[x] 
could be written as mapcar[chcon[x]; character]. 



fcharacter[n] 
gensym[char] 



fast version of character that compiles open. 

Generates a new atom of the form xnnnn, where 
x» char (or A if char is NIL) in which each of the 



See footnote 2. 
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n's is a digit. Thus, the first one generated is 
AOOOl, the second A0002, etc. gensym provides a 
way of generating new atoms for various uses 
within the system. The value of gennum . initially 
10000, determines the next gensym . e.g. if gennum 
is set to 10023, gensymC ]«A0024. 

The term oensym is used to indicate an. atom that was produced by the function 
gensym . Atoms generated by gensym are the same as any other literal atomst 
they haue property lists, and can be given function definitions , Mote that the 
atoms are not guaranteed to i^e new. 

For example, if the user has previously created AOOIZ, either by typing it in, 
or via pack or gensym itself, when gennum gets to 10011, the next value 
returned by gensym will be the A0012 already in existence. 

mapatoms[fn] Applies fn to every literal atom in the system, 

e.g. mapatoms[(LANBOA(X)(AND(SUBRP X)(PRINT X))}] 
will print every subr . Value of roapatoms is NIL. 

10.2 String Functions 

stringp[x] Is x if x a string, NIL otherwise. Note: if x is 

a string, nlistpCx] is T, but atomCx] is NIL. 

strequalCx;y] Is x if x and ^ both strings and equal, i.e. 

print the same, otherwise NIL. Equal uses 
strequal . Note that strings may be equal without 
being e<i. 

mkstring[x] Value is string corresponding to prinl of x* 

rstring[] Reads a string - see Section 14. 
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substringCx;n;iii] Value is the substring of x consisting of the nth 

thru mth characters of x. If in is NIL, the 
substring is the nth character of x thru the end 
of X. n and m can be negative numbers, as with 
nthchar . Returns NIL if the substring is not well 
defined, e.g. n or m > ncharsCx] or 
< ninus[ ncharsCx]] or n corresponds to a character 
in X to the right of the character indicated by m. 

If X is not a string, equivalent to 
substring[inlcstringCx];n;ni], except substring does 
not have to actually make the string if x is a 
literal atom.^ For example, 
substring[(A B C);4;6]-"B C". 

onc[x} get next character of string x* Returns the next 

character of the string, (as an atom), and removes 
the character from the string. Returns NIL if x 
is the null string. If x isn't a string, a string 
is made. Used for sequential access to characters 
of a string. 

Note that if x is a substring of ^, gncCx] does 
not remove the character from 2, i.e. gnc doesn't 
physically change the string of characters. Just 
the pointer and the byte count. ^ 



See string storage section that follows. 
See string storage section that follows. 
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Olc[x3 gets last character of string x* Above remarks 

about gnc also supply to glc » 

concat[X|;x2; . . . ;x^] lambda nospread function. Concatenates (copies 

of) any number of strings. The arguments are 
transformed to strings if they aren't strings. 
Value is the new string, e.g. 

concatC"ABC";0EF;"6HI"] « "ABCDEFGHI". The value 
of concat[] is the null string, "". 

rplstringCx;n;y] Reglace characters of string x beginning at 

character n with string n may be positive or 
negative, x and x are converted to strings if 
they aren't already. Characters are smashed into 
(converted) x* Returns new x* Error if there is 
not enough room in x for ^, i.e. the new string 
would be longer than the original. Note that if x 
is a substring of z, 2 will also be modified by 
the action of rplstring . 

mkatomCx] Creates an atom whose pname is the same as that of 

the string x or if x isn*t a string, the same as 
that of mkstringCx], e.g. mkatomC(A B C)] is the 
atom %(AX BX CX). If atom would have > 99 
characters, causes an error, ATOM TOO LONG. 



If hot a string, x will already have been partially modified since 

rplstring does not know'whether x ^^^^ 'fit' without actually attempting 
the transfer. 
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Searching Strings 



strpos is a function for searching one string looking for another. Roughly it 
corresponds to member , except that it returns a character position number 
instead of a tail. This number can then be given to substring or utilized in 
other calls to strpos . 

strposC X ; y ; start ; skip ; anchor ; tail ] 

X and Y. ^re both strings (or else they are 
converted automatically). Searches ^ beginning at 
character number start , (or else 1 if start is 
NIL) and looks for a sequence of characters equal 
to X* If a match is found* the corresponding 
character position is returned, otherwise HIL, 
e.g., 

StrposC "ABC" , "XYZABCOEF" ]=4 
StrposC "ABC" , "XYZABCDEF" ; 5 ]«NIL 
StrposC "ABC" , "XYZABCOEFABC" ; 5]«10 

skip can be used to specify a character in x that 
matches any character in e.g. 
StrposC "A&C&" ; "XYZABCDEF" ;NIL;&]«4 

If anchor is T, strpos compares x with the 
characters beginning at position start , or 1. If 
that comparison fails, strpos returns NIL without 
searching any further down jr. Thus it can be used 
to compare one string with some portion of another 
string, e.g. 

StrposC "ABC" ; "XYZABCDEF" ; NIL ; NIL ; T ]«NIL 
StrposC "ABC" ; "XYZABCDEF" ;4 ;NIL ; T3«4 
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Finally, if tall is T, the value returned by 
strpos if successful is not the starting position 
of the sequence of characters corresponding to x, 
but the position of the first character after 
that, i.e. starting point plus nchars[x] e.g. 
strposC "ABC" ; "XYZABCDEFABC" ; NIL ; NIL ; NIL ; T]-7 . 
Note that strpos["A";"A";NIL;NIL;NIL;T>2, even 
though "A" has only one character. 

Example Problem 

Given the strings x» and z, write a function foo that will make a string 
corresponding to that portion of x between and z, e.g. 

foo["NOW IS THE TIME FOR ALL 6000 MEN"; "IS"; "FOR"] is " THE TIME ". 

Solution: 

(FOO 

[LAMBDA (X Y Z) 

(AND (SETQ Y (STRPOS Y X NIL NIL NIL T)) 
(SETQ Z (STRPOS Z X Y)) 
(SUBSTRING X Y (SUBl Z]) 



strposl[a;5tr;start;neg] str is a string (or else it is converted 

automatically to a string), a is a list of 
characters or character codes. strposl searches 
str beginning at character number start (or else 1 
start «NIL) for one of the characters in a. If 
one is found, strposl returns as its value the 



If any element of a is a number, it is assumed to be a character code. 
Otherwise, it is converted to a character code via chconl . Therefore, it 
is more efficient to call strposl with a a list of character codes . 
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corresponding character position » otherwise NIL. 
E.g., strposl[(A B C);"XYZBCD">4. If nea«T. 
strposl searches for a character not on a, e.o«» 
strposl[(A B C); ••ABCDEF";NIL;T]«4. 

If a is an array, it is treated as a bit table. 
The bits of (ELT A 1) correspond to character 
codes 0 to 43Q, of (ELT A 2) to codes 44Q to 107Q, 
etc. Thus an array whose Tirst element was 17Q 
would be equivalent to a list (40Q 41Q 42Q 4dQ) or 
(X„ ! X" #). 

If a is not a bit table (array), strposl first converts it to a bit table using 
makebittable described below. If strposl is to be called frequently with the 
same list of characters, a considerable savings can be achieved by converting 
the list to a bit table once, and then passing the bit table to strposl- as its 
first argument. 

Dakebittable[l;neg;a] makes a bit table suitable for use by strposl . 1 

and! neg are as for strposl . If a is not an array 
with at least 4 elements, makebittable will create 
an array and return that as its value. Otherwise 
it uses (and changes) a. 

Note: if neg aT, strposl must call makebittable whether a is a list or an 
array. To obtain bit table efficiency with nefl=T, makebittable should be 
called with negaT, to construct the "inverted" table, and the resulting table 
(array) should be given to strposl with negaNIL. 
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string Storage 



A string is stored in 2 parts; the characters of the string, and a pointer to 
the characters. The pointer* or 'string pointer', indicates the byte at which 
the string begins and the length of the string. It occupies one word of 
storage. The characters of the string are stored five characters to a word in 
a portion of the INTERLISP address space devoted exclusively to storing 
characters. 

Since the internal pname of literal atoms also consists of a pointer to the 

beginning of a string of characters and a byte count, conversion between 

literal atoms and strings does not require any additional storage for the 

a 

characters of the pname , although one cell is required for the string pointer. 



When the conversion is done internally, e.g. as in substring , strpos . or 
strposl , no additional storage is required for using literal atoms Instead of 
strings. 



The use of storage by the basic string functions is given below: 

mkstringCx] x string no space 

X literal atom new pointer 

other new characters and pointer 



substring[x;n;m] x string new pointer 

X literal atom new pointer 
other new characters and pointer 



Except when the string is to be smashed by rplstring . In this case, its 
characters must be copied to avoid smashing the pname of the atom. 
rplstring automatically performs this operation. 
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gnc[x3 and glc[x] x string 

other 

concat[Xj;x2; • > •x^^] ergs any type 
rplstring[x;n;y] x string 



X other 
y any type 



no space, pointer is modified 

like mkstrina . but doesn't make much 

sense 

new characters for whole new 
string, one new pointer 

no new space unless characters are in 
pnane space (as result of 
mkstring[atom]) in which case x is 
quietly copied to string space 
new pointer and characters 
type of y doesn't matter 



10.3 Array Functions 

Space for arrays and compiled code are both allocated out of a common array 
space. Arrays of pointers and unboxed numbers may be manipulated by the 
following functions: 

array[n;p;v] This function allocates a block of n*Z words, of 

which the first two are header information. The 
next p < n are cells which will contain unboxed 
numt>ers, and are initialized to unboxed 0. The 
last n-p > 0 cells will contain pointers 
initialized with v, i.e., both car and cdr are 
available for storing information, and each 
initially contain v. If £ is NIL, 0 is used 
(i.e., an array containing all INTERLISP 
pointers). The value of array is the array, also 
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called an array pointer. If sufficient space is 
not available for the array, a garbage collection 
of array space* 6C: 1, is initiated. If this is 
unsuccessful in obtaining sufficient space, an 
error is generated, ARRAYS FULL. 



Array- pointers print as 0nt where n is the octal representation of the pointer, 
Mote that 0n will be read as a literal atom, and not an array pointer. 



arraysize[a3 



Returns the size of array a. Generates an error, 
AR6 NOT ARRAY, if a is not an array. 



arraypCx] 



Value is X if X is an array pointer othervrise NIL. 
No check is made to ensure that x actually 
addresses the beginning of an array. 



elt[a;n} 



Value is nth element of the array a^^ elt 
generates an error, ARG NOT ARRAY, If a is not the 
beginning of an array. If n corresponds to the 
unboxed region of a, the value of elt Is the full 
36 bit word, as a boxed Integer. If n corresponds 
to the pointer region of a, the value of elt is 
the car half of the corresponding element. 



seta[a;n;v] 



sets the nth element of the array a. Generates an 



10 



11 



elt[a;l] is the first element of the array (actually corresponds to the 3rd 
cell because of the 2 word header). 

arrayp is true for pointers into the middle of arrays , but elt and seta 
must be given a pointer to the beginning of an array, i.e., a value of 

array . 
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error, ARG NOT ARRAY, if a is not the beginning 
of an array. If n corresponds to the unboxed 
region of a, v must be a number, and is unboxed 
and stored as a full 36 bit word into the nth 
element of a. If n corresponds to the pointer 
region of a, y replaces the car half of the nth 
element. The value of seta is v. 

^ote that seta and elt are always inverse operations . 



eltd[a;n] same as elt for unboxed region of a, but returns 

cdr half of nth element, if n corresponds to the 
pointer region of a. 



setd[a;n;v] same as seta for unboxed region of a, but sets cdr 

half of nth element, if n corresponds to the 
pointer region of a. The value of setd is v. 



In other words, eltd and setd are always inverse operations. 



10.4 Storage Functions 



reclaim[n] Initiates a garbage collection of type n. Value 

of reclaim is number of words available Tfor that 
type) after the collection. 



Garbage collections , whether invoked directly by the user or indirectly by need 
for storage, do not confine their activity solely to the data type for which 
they were called, but automatically collect some or all of the other types (see 

Section 3). 



ntyp[x3 Value is type number for the data type of 

INTERLISP pointer x, e.g. ntyp[(A . B)] is 8, the 
type number for lists ^ Thus GC: 8 indicates a 
garbage collection of list words. 
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type 



number 



arrays, compiled code 
stack positions! 
list words 
atoms 

floating point bunbers 
large integers 
small integers 
string pointers 
pname storage 
string storage 



1 
2 
8 
12 
16 
18 
20 
24 
28 
30 



eqCntyp[x];n] 

message is a string or atom to be printed (using 
prinl ) wherever a garbage collection is begun. If 
message «T, its standard setting, 6C: is printed, 
followed by thd type number. When the garbage 
collection is complete, two numbers are printed 
the number of Words collected for that type, and 
the total numbeir of words available for that type, 
i.e. allocated !but not necessarily currently in 
use (see ninfs l^elow). 

Example : 
«-RECUIN(18) 

GC: 18 

511, 3071 FREE WORDS 
3071 

«-RECUIH(12) 

GC: 12 

1020, 1020 FREE WORDS 
1020 

If message »NIL. no garbage collection message is 
printed, either on entering or leaving the garbage 
collector. Value of gcgag is old setting. 
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iDinfs[ii;typ] < Sets the minimuiD amount of free storage which will 

be maintained by the garbage collector for data 
types of type number typ . If after any garbage 
collection for that type, fewei^ than n free words 
are present, sufficient storage will be added (in 
512 word chunks) to raise the level to n. 

If typ«NIL. 8 is used, i.e. the minfs refers to 
list words. 

If inaNILp minfs returns the current minfs setting 
for the corresponding type. 

A minfs setting can also be changed dynamically, even during a garbage 
collection, by typing control-S followed by a number, followed by a period. 
If the control-S was typed during a garbage collection, the number is the new 
minfs setting for the type being collected, otherwise for type 8, i.e. list 
words . 

Motet A garbage collection of a 'related* type may also cause more storage to 
be assigned to that type* See discussion of garbage collector algorithm. 
Section 3. 

storage[flg] Prints amount of storage (by type number) used by 

and assigned to the user, e.g. 



When the control-S is typed, INTERLISP immediately clears and saves the 
input buffer, rings the bell, and waits for input, which is terminated by 
any non-number. The input buffer is then restored, and the program 
continues. If the input was terminated by other than a period, it is 
ignored. 



10.16 



♦-STORAdEO 



TYPE 


USED 


ASSIGNED 


1 


80072 


87552 


8 


7970 


9216 


12 


7032 


7680 


16 


0 


512 


18 


1124 


2560 


24 


118 


512 


28 


4226 


4608 


30 


573 


1024 


SUM 


101115 


113664 



If flgaT, includes storage Used by and assigned to 
the system. Value is NIL. 



gctrp[n] garbage collection tra£. Causes a (simulated) 

control-H interrupt when the number of free list 
words (type 8) remaining equals n, i.e. when a 
garbage collection would occur in n more conses. 
The message GCTRP is printed, the function 
interrupt (Section 16) is called, and a break 
occurs. Note that by advising (Section 19) 
interrupt the user can program the handling of a 

IS 

gctrp instead of going into a break. 

Value of gctrp is its last setting. 

gctrpC-1] will 'disable' a previous gctrp since 
there are never -1 free list words, gctrp is 
initialized this way. 



For gctrp interrupts, interrupt is called with intype (its third argument) 
equal to 3. If the user does not want to go into a break, the advice 
should still allow interrupt to be entered, but first set intype to -1. 
This will cause Interrupt to "quietly" go away by calling the function that 
was interrupted. The advice should not exit interrupt via return , as in 
this case the function that was about to be called when the interrupt 
occurred would not be called. 
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gctrp[] returns number of list words left, i.e. 
number of conses until next type 8 garbage 
collection, see Section 21. 

conscount[] returns number of conses since 
INTERLISP started up. If n is not NIL, resets 
conscount to n. 

Stores X into memory location a. Both x and a 
must be numbers. 

Value is the number in memory location a, i.e. 
boxed. 
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Page 
Numbers 

AOOOn (gensym) 10.5 

ARG NOT ARRAY (error message) 10.13-14 

ARRAY[N;P;V] SUBR 10.12 

array functions 10.12-14 

array header , 10.12 

ARRAYP[X] SUBR 10.13 

ARRAYS FULL (error message) 10.13 

ARRAYSIZECA] 10.13 

ATOM TOO LONG (error message) 10.2,7 

bell (typed by system) 10.16 

CHARACTER[N] SUBR 10.4 

character atoms 10.2 

character codes 10.4 

CHCON[X;FLG] SUBR 10.4 

CHC0N1[X] SUBR 10.4 

CLOSER[A;X] SUBR 10.18 

compiled code 10.12 

C0NCATCXl;X2;...;Xn] SUBR* 10.7,12 

CONSCOUNT[N] SUBR 10.18 

control-H 10.17 

control-S 10.16 

DCHCON[X;SCRATCHLIST;FLG] 10.4 

DUNPACK[X;SCRATCHLIST;FLG3 10.3 

ELT[A;N] SUBR 10.13 

ELTD[A;N3 SUBR 10.14 

FCHARACTER[N] SUBR 10.4 

garbage collection 10.13-18 

GC: (typed by system) 10.15 

GC: 1 (typed by system) 10.13 

GC: 8 (typed by system) 10.14 

GCGAG[ MESSAGE] SUBR 10.15 

GCTRP[N] SUBR 10.17 

GENNUM (system variable/parameter) 10.5 

GENSYM[CHAR] 10.4-5 

GLC[X] SUBR 10.7,12 

GNC[X] SUBR 10.6,12 

input buffer 10.16 

INTERRUPTC INTFN ; INTAR6S ; INTYPE ] 10.17 

literal atoms ; 10.11 

MAKEBITTABLE[L;NEG;A] 10.10 

MAPATOMS[FN] SUBR 10.5 

MINFS[N;TYP] SUBR 10.16 

MKATOMCX] SUBR 10.7 

MKSTRING[X] SUBR 10.5,11 

NCHARS[X] SUBR 10.3 

NTHCHARCX;N] SUBR 10.3 

NTYP[X] SUBR 10.14 

null string 10.6-7 

OPENR[A] SUBR 10.18 

PACKCX] SUBR 10.2 

PACKC[X] SUBR 10.4 

pnames 10.1-4,11 

prin2-pnames 10.1,3-4 

print name ^ 10. 1 

RADIX[N] SUBR 10. 1 

RECLAINCN] SUBR 10.14 
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RPLSTRING[X;N;Y] SUBR 10.7.12 

RSTRING[] SUBR 10.5 

searching strings 10.8-10 

SETA[A;N;V] 10.13 

SETD[A;N;V] 10.14 

STORAGECFLG] 10,16 

STREOUAL[X;Y] 10.5 

string characters 10.11 

string functions 10.5-10 

string pointers 10.6,11 

string storage 10.11-12 

STRINGP[X] SUBR 10.5 

STRPOS[X;Y;START;SKIP;ANCHOR;TAIL] 10.8-9 

STRPOSL[A;STR;START;NEG] 10.9-10 

SUBSTRING[X;N;M] SUBR 10.6.11 

type numbers 10.14 

TYPEP[X;N] 10.15 

unboxed numbers (in arrays) 10.12 

UNPACK[X;FLG] SUBR 10.2-3 

# (followed by a number) 10.13 
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SECTIOM 11 
FUNCTIONS WITH FUNCTIONAL ARGUMENTS 



As in all LISP 1.5 Systems, arguments can be passed which can then be used as 
functions. However, since car of a form is never evaluated, apply or apply * 
must be used to call the function specified by the value of the functional 

argument. 

Functions which use functional arguments should use variables with obscure 
names to avoid possible conflict with variables that are used by the functional 
argument. For example, all system functions standardly use variable names 
consisting of the function name concatenated with x or fn, e.g. mapx . Note 
that by specifying the free variables used in a functional argument as the 
second argument to function , thereby using the INTERLISP FUNARG feature, the 
user can be sure of no clash. 

function[x:y] is an nlambda function. If ^sNIL, the value of 

function is identical to quote , for example, 
(MAPC LST (FUNCTION PRINT)) will cause mapc to be 
called with two arguments the value of 1st and 
PRINT. Similarly, 

(HAPCAR LST ( FUNCTION (LAMBDA(Z) (LIST (CAR Z))))) 
will cause mapcar to be called with the value of 
1st and (LAMBDA (Z) (LIST (CAR Z))). When 
compiled, function will cause code to be compiled 
2S> quote will not. Thus 
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(MAPCAR LST (QUOTE (LAMBDA — ))) will cause mapcar 
to be called with the value of 1st and the 
expression (LAMBDA --). The functional argument 
wilJL therefore still be interpreted. The 
corresponding exjiression using function will cause 
a dummy function to be created with definition 
(LAMBDA --)» and then compiled, mapcar would then 
be called with the value of 1st and the name of 
the dummy function. See Section 18. 

If }i[ is not NIL» it is a list of variables that 
are (presumably) used freely by x. In this case, 
the value of function is an expression of the form 
(FUhFARG X array) » where array contains the 
variable bindings for those variables on y.* 
Funarg is described on page 11.5-7. 

map[mapx;mapfnl ;mapfn2] If mapfnZ is NIL, map applies the function mapfnl 

to successive tails of the list mapx . That is, 
first it computes mapfnlCmapx], and then 
mapfnl[cdr[mapx]], etc., until mapx is exhausted.^ 
If mapfnZ is provided, mapfnZCmapx] is used 
instead of cdr[mapx] for the next call for mapfnl , 
e.g., if mapfnZ were cddr , alternate elements of 
the list would be skipped. 

The value of ma£ is NIL. map compiles open. 



i.e., becomes a non-list. 
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mapc[napx;napfnl;napfn2] Identical to ma£, except that mapfnUcarCfflapx]] is 

computed at each Iteration instead of 
napfnlCoapx], i.e., mapc works on elements, map on 
tails. The value of mapc is NIL. mapc compiles 
open. 

maplist[fflapx;mapfnl;mapfn2i successively computes the same values that map 

would compute; and returns a list consisting of 
those values, roaplist compiles open. 

mapcar[mapx;mapfnl;mapfn2] computes the same values that mapc would compute, 

and returns a list consisting of those values, 
e.g. mapcarCx;FNTYP] is a list of fntyps for each 
element on x. roapcar compiles open. 

mapconCmapximapfnlimapfnZ] Computes the same values as ma£ and maplist but 

nconcs these values to form a list which it 
returns, mapcon compiles open. 

fflapconc[mapx;mapfnl;mapfn2] Computes the same values as mapc and roapcar , but 

nconcs the values to form a list which it returns. 
roapconc compiles open. 

Note that mapcar creates a new list which is a mapping of the old list in that 
each element of the new list is the result of applying a function to the 
corresponding element on the original list, mapconc is used when there are a 
variable number of elements (Including none) to be inserted at each iteration, 
e.g. mapconcCX;( LAMBDA (Y) (AND Y (LIST Y)))] will make a list consisting of x 
with all NILS removed, mapconcCX;( LAMBDA (Y) (AND (LISTP Y) Y))] will make a 
linear list consisting of all the lists on x, e.g. if applied to 
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((A B) C (D E F) (G) H I) will yield (A B D E F G).^ 



subset[niapx;niapfnl ;Diapfn2] applies mapfnl to elements of roapx and returns a 

list of those elements for which this application 
is inon-NIL, e.g., 

subset[(A B 3 C 4);NUMBERP] » (3 4). 

mapfnZ plays the same role as with map , mapc , et 

al. subset compiles open. 

niap2c[mapx;mapy;mapfnl ;mapfn2] Identical to mapc except mapfnl is a function 

of two arguments, and mapfnl[car[fflapx];car[mapy]] 
is computed at each interation.^ Terminates when 
eitAer mapx or mapy are exhausted. 

map2car[inapx:mapy;mapfnl ;mapfn2] Identical to mapcar except mapfnl is a 

function of two arguments and 

mapfnl[car[mapx];car[mapy]] is used to assemble 
the new list. Terminates when either mapx or mapy 
is exhausted. 

Note: CLISP (Section 23) provides a more general and complete facility for 
expressing iterative statements, e.g. (FOR X IN Y COLLECT (CAOR X) WHEN 
(NUNBERP (CAR X)) UNTIL (NULL X)). 



Note that since ma pconc uses nconc to string the corresponding lists 
together, in this example, the original list will be clobbered, i.e. it 
would now be ((A B D E F G) C (0 E F G) (G) H I) . If this is an undesirable 
side effect, the functional argument to mapconc should return instead a top 
level copy, e.g. in this case, use (AND (LISTP Y) (APPEND Y)). 



mapfn2 is still a function of one argument, and is applied twice on each 
iteration; mapfn2[ roapx] gives the new roapx , mapfn2[mapy] the new mapy . cdr 
is used if mapfn2 is not supplied, i.e., is NIL. 



roapr in t[ 1st ; f lie ; left ; right ; sep ; pf n ; lispxprintf Ig ] 

is a general printing function. It cycles through 
1st applying £fn (or print if gfn not given) to 
each elenent of 1st. Between each application, 
maprint performs prinl of sep , or " " if sep sNIL. 

loft is given, it is printed (using prinl ) 
initially; if right is given it is printed (using 
prinl ) at the end. 

For example, maprint[x;NIL;X( ;%)] is equivalent to 
prinl for lists. To print a list with commas 
between each element and a final * . ' one could use 
maprint[x;T;NIL;X. i%, ]. 

If lispxprintflg « T, lispxprinl is used for prinl 
(see Section 22). 

Napdl,searchpdl See Section 12. 

mapatoms See Section 5. 

every, some, notevery, notany See Section 5. 

Funarg 

function is a function of two arguments, x> ^ function, and y, ^ l^^t of 
variables used freely by x. If £ is not NIL, the value of function is an 
expression of the form (FUNARG x array), where array contains the bindings of 
the variables on )r at the time the call to function was evaluated, funarg is 
not a function itself. Like LANBDA and NLANBDA, it has meaning and is 
specially recognized by INTERLISP only in the context of applying a function to 
arguments. In other words, the expression (FUNARG x array) is used exactly 
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like a function. When a funarg is applied, the stack is modified so that the 
bindings contained in the array will be in force when Xt the function, is 

called.^ 

For example, suppose a program wished to compute (FOO X (FUNCTION FIE}}, and 
fie used and z as free variables. If foo rebound ^ and 2, fie would obtain 
the rebound values when it was applied from inside of foo. By evaluating 
instead (FOO X (FUNCTION FIE (Y Z))), foo would be called with 
(FUNARG FIE array) as its second argument, where array contained the bindings 
of Y. <^nd z (at the time foo was called). Thus when fie was applied from inside 
of foo . it would 'see* the original values of £ and z. 

However, funarg is more than just a way of circumventing the clashing of 
variables. For example, a funarg expression can be returned as the value of a 
computation, and then used 'higher up', e.g., when the bindings of the 
variables contained In array were no longer on the stack. Furthermore, if the 
function in a funarg expression sets any of the variables contained In the 
array, the array Itself (and only the array) will be changed. For example, 
suppose foo is defined as 

(LAMBDA (LST FN) (PROG (Y Z) (SETQ Y &) (SETQ Z &) ... (MAPC LIST FN) ...)) 
and (FOO X (FUNCTION FIE (Y Z))) is evaluated. If one application of fie (by 
the mapc in foo) changes y. and z, then the next application of fie will obtain 
the changed values of )r and z resulting from the previous application of fie , 
since both applications of f ie come from the exact same funarg object, and 
hence use the exact same array. The bindings of and z bound inside of foo, 
and the bindings of ^ and z a^ove foo would not be affected. In other words. 



LAMBDA, NLAMBDA, and FUNARG expressions are sometimes called 'function 
objects* to distinguish them from functions, i.e., literal atoms which have 
function definitions. 

The implementation of funarg is described in Section 12. 
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the variable bindings contained in array are a part of the function object, 
i.e., the funarg carries its environment with it. 

Thus by creating a funarg expression with function , a program can create a 
function object which has updateable binding(s) associated with the object 
which last between calls to it, but are only accessible through that instance 
of the function. For example, using the funarg device, a program could 
maintain two different instances of the same random number generator in 
different states, and run them independently. 

Example 

If foo is defined as (LAMBDA (X) (COND ((ZEROP A) X) (T (MINUS X))) and fie as 
(LAMBDA NIL (PROG (A) (SETQ A 2) (RETURN (FUNCTION FOO)))). then if we perform 
(SETQ A 0), (SETQ FUM (FIE)), the value of fum is FOO, and the value of 
(APPLY* FUN 3) is 3, because the value of A at the time foo is called is 0. 

However if fie were defined instead as 

(LAMBDA NIL (PROG (A) (SETQ A 2) (RETURN (FUNCTION FOO (A))))), the value of 
fum would be (FUNARG FOO array) and so the value of (APPLY* FUM 3) would be -3, 
because the value of A seen by foo is the value A had when the funarg was 
created inside of fie, i.e. 2. 
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APPLY[FN;ARGS] SUBR 11.1 
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CLISP 11.4 
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SECTION 12 

VARIABLE BINDINGS AND PUSH DOWN LIST FUNCTIONS 



A number of schenes have been used in different implementations of LISP for 
storing the values of variables. These include: 

1. Storing values on an association list paired with the variable names. 

2. Storing values on the property list of the atom which is the name of 
the variable. 

3. Storing values in a special value cell associated with the atom name, 
putting old values on a pushdown list, and restoring these values when 
exiting from a function. 

4. Storing values on a pushdown list. 

The first three schemes all have the property that values are scattered 
throughout list structure space, and, in general, in a paging environment would 
require references to many pages to determine the value of a variable. This 
would be very undesirable in our system. In order to avoid this scattering, 
and possibly excessive drum references, we utilize a variation on the fourth 
standard scheme, usually only used for transmitting values of arguments to 
compiled functions; that is, we place these values on the pushdown list.^ But 



Also called the stack. 
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since we use an interpreter as well as a compiler, the variable names must also 
be kept. The pushdown list thus contains pairs, each consisting of a variable 
name and its value. Each pair occupies one word or 'slot' on the pushdown 
list, with the name in the left half, i.e. cdr, and the value in the right 
half, i.e. car. The interpreter gets the value of a variable by searching back 
up the pushdown list looking for a 'slot' for which cdr is the name of the 
variable, car is then its value. 

One advantage of this scheme is that the current top of the pushdown stack is 
usually in core, and thus drum references are rarely required to find the value 
of a variable. Free variables work automatically in a way similar to the 
association list scheme. 

An additional advantage of this scheme is that it is completely compatible with 
compiled functions which pick up their arguments on the pushdown list from 
known positions, instead of doing a search. To keep complete compatibility, 
our compiled functions put the names of their arguments on the pushdown list, 
although they do not use them to reference variables. Thus, free variables can 
be used between compiled and interpreted functions with no special declarations 
necessary. The names on the pushdown list are also very useful in debugging, 
for they make possible a complete symbolic backtrace in case of error. Thus 
this technique, for a small extra overhead, minimizes drum references, provides 
symbolic debugging information, and allows completely free mixing of compiled 
and interpreted routines. 

There are three pushdown lists used in INTERLISP: the first is called the 
parameter pushdown list, and contains pairs of variable names and values, and 
temporary storage of pointers; the second is called the control pushdown list, 
and contains function returns and other control information; and the third is 
called the number stack and is used for storing temporary partial results of 
numeric operations. 
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However, it is more convenient for the useij' to consider the push-down list as a 
single "list" containing the names of functions that have been entered but. not 
yet exited, and the names and values of the corresponding variables. The 
multiplicity of pushdown lists in the actual implementation is for efficiency 
of operation only. 

The Push-Down List and the Interpreter 

In addition to the names and values of arguments for functions, information 
regarding partially-evaluated expressions is kept on the push-down list. For 
example, consider the following definition of the function fact (intentionally 
faulty): 

(FACT 

[LAMBDA (N) 
(COND 

((ZEROP N) 
L) 

(T (ITIMES H (FACT (SUBl N]) 

In evaluating the form (FACT 1), as soon as fact is entered, the interpreter 
begins evaluating the implicit progn following the LAMBDA (see Section 4). The 
first function entered in this process is cond* cond begins to process its 
list of clauses. After calling zerop and getting a NIL value, cond proceeds to 
the next clause and evaluates T* Since T is true, the evaluation of the 
implicit progn that is the consequent of the T clause is begun (see Section 4). 
This requires calling the function itimes. However before itimes can be 
called, its arguments must be evaluated. The first argument is evaluated by 
searching the stack for the last binding of N; the second involves a recursive 
call to fact, and another implicit progn . etc. 

Note that at each stage of this process, some portion of an expression has been 
evaluated, and another is awaiting evaluation. The output below illustrates 
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this by showing the state of the push-down list at the point in the computation 
of (FACT 1) when the unbound atom L is reached. 



•-FACT(l) 

U.B.A. 

(L BROKEN) 

:BTV! 

•FORM* (BREAKl L T L NIL #34047) 
#0 (L) 

#0 (((ZEROP N) L) (T (ITINES N (FACT (SUBl N))))) 1 
COND 

•FORM* (COND ((ZEROP N) L) (T (ITIHES N (FACT (SUBl N))))) 

#0 ((COND ((ZEROP N) L) (T (ITIHES N (FACT (SUBl N)))))) 2 

N 0 
FACT 

*FORM* (FACT (SUBl N)) 
#2 ITIMES 

#0 ((FACT (SUBl N))) 3 
#0 1 4 
*FORM* (ITIMES N (FACT (SUBl N))) 

#0 ((ITIMES N (FACT (SUBl N)))) 5 

#0 (((ZEROP N) L) (T (ITIMES N (FACT (SUBl N))))) 6 
COND 

*FORM* (COND ((ZEROP N) L) (T (ITIHES N (FACT (SUBl N))))) 

#0 ((COND ((ZEROP N) L) (T (ITIHES N (FACT (SUBl N)))))) 7 

N 1 
FACT 

**TOP** 



Internal calls to eval . e.g., from cond and the interpreter, are marked on the 
push-down list by a special mark called an eval-blip. eval-blips are indicated 
by the appearance of (VAG 64) in the left-half, i.e. the variable name 
position, for that slot. They are printed by the backtrace as *FORM*. The 
genealogy of *FORN*'s is thus a history of the computation. Other temporary 
information is frequently recorded on the push-down list in slots for which the 
'variable name' is (VAG 0), which prints as #0. In this example, this 
information consists of (1) the tail of a list of cond clauses, (2) the tail of 
an implicit progn . i.e., the definition of fact, (3) the tail of an argument 
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list, (4) the value of a previously evaluated argunent, (5) the tail of a cond 
clause whose predicate evaluated to true, and (6) and (7) same as (i) and (2). 

Note that a function is not actually entered and does not appear on the stack, 
until its argunents have been evaluated.^ Also note that the #0 'bindings' 
comprise the actual working storage. In other words, in the above example, if 
a (lower) function changed the value of the binding at (1) (not recommended) 
the cond would continue interpreting the new binding as a list of cond clauses. 
Similarly, if (4) were changed, the new value would be given to itimes as its 
first argument after its second argument had been evaluated, and itimes was 
actually called. 

The Pushdown List and Compiled Functions 

Calls to compiled functions, and the bindings of their arguments, i.e. names 
and values, are handled in the same way as for interpreted functions (hence the 
compatibility between interpreted and compiled functions). However, compiled 
functions treat free variables in a special way that interpreted functions do 
not. Interpreted functions "look up" free variables when the variable is 
encountered, and may look up the same variable many times. However, compiled 
functions look up each free variable only once. Whenever a compiled function 
is entered, the pushdown list is scanned and the most recent binding for each 
free variable used in the function is found (or if there is no binding, the 
value cell is obtained) and stored in the right half of a slot on the stack (an 
unboxed 0 is stored in the left half to distinguish this 'binding' from 



except for functions which do not have their arguments evaluated (although 
they themselves may call aval , e.g. cond ). 

A list of all free variables is generated at compile time, and is in fact 
obtainable from the compiled definition. See Section 18. 
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ordinary bindings). Thus, folloi«ing the bindings of their arguments, compiled 
functions store on the pushdown list pointers to the bindings for each free 
variable used in the function. 

In addition to the pointers to free variable bindings, compiled functions 
differ from interpreted functions in the way they treat locally bound 
variables, i.e. progs and open lambdas . Whereas in interpreted functions progs 
and open lambdas are called in the ordinary way as functions, in compilation, 
progs and open lambdas disappear, although the variables bound by them are 
stored on the stack in the conventional manner so that functions called from 
inside them can reference the variables. These variables appear on the stack 
following the arguments to the compiled function (if any) and the free variable 
pointers (if any). The only way to determine dynamically what variables are 
bound locally by a compiled function is to search the stack from the first slot 
beyond the last argument to the function (which can be found with stknargs and 
stkarg described below), to the slot corresponding to the first argument of the 
next function. Any slots encountered that contain literal atoms in their left 
half are local bindings. 

Pushdown List Functions 

NOTE: Unless otherwise stated, for all pushdown list functions, pos is a 
position on the control stack. If £os is a literal atom other than NIL, 
(STKPOS pos 1) is used. In this case, if £os is not found, i.e., stkpos 
returns NIL, an ILLEGAL STACK AR6 error is generated. 

stkpos[fn;n;pos] Searches the control stack starting at pos for the 

nth occurrence of fn. Returns control stack 
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position of that fn if found, olso NIL. If n is 
positive, searchfs backward (nornal usagt)* If n 
is negative, searches forward, i.e., down the 
control stack. For exanple, stkposCF00;-'2;FIE] 
finds second call to FOO after (below) the last 
call to FIE. If n is NIL, 1 is used. If £0S is 
NIL, the search starts at the current position. 
stkpos[] gives the current position. 

stknth[n;pos] Value is the stack position (control stack) of the 

nth function call relative to position pos . If 
pos is NIL, the top of stack is assumed for n > 0, 
and the current position is assumed for n < 0, 
i.e., stknth[-l] is the call before stknth, 
stknth[l] is the call to evalgt at the top level. 
Value of stknth is NIL if there is no such call - 
e.g., stknthClOOOO] or stknthC-10;stknthC5]]. 

fstknth[n;pos] version of stknth that compiles open. 

stkname[pos] Value is the name of the function at control stack 

position £os. In this case, pos must be a real 
stack position, not an atom. 

In summary, stkpos converts function names to stack positions, stknth converts 
numbers to stack positions, and stkname converts positions to function names. 



A stack position is a pointer to the corresponding slot on the control or 
parameter stack, i.e., the address of that cell. It prints as an unboxed 
number, e.g., #32002, and its type is 2 (Section 10). 
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Information about the variables bound at a particular function call can be 
obtained using the following functions.: 



stknargs[pos] 



Value is the number of ai^guments bound by the 
function at position pos . 



stlcarg[n;pos] 



Value is a pointer to the nth argument (named or 
not)^ of the function at position £os, i.e., the 
value is a parameter stack position, car of this 
pointer gives the value of the binding, cdr the 
name . n«l corresponds to the first argument at 
pos .. n can be 0 or negative, i.e., stkargC0;FOO] 
is a pointer to the slot immediately before the 
first argument to FOO, stkarg[-l;FOO] the one 
before that, etc. 



fstkarg[n;pos] 



version of stkarq that compiles open. 



Note that the user can change (set) the value of a particular binding by 
performing an rplaca on the value of stkarg . Similarly, rplacd changes (sets) 
the name. 



The value of stkarg is a position (slot) on the parameter stack. There is 
currently no analogue to stkn th for the parameter stack. However, the 
parameter stack is a contiguous block of memory, so to obtain the slot previous 
to a given slot, perform vagCsublClocCslot]]]; to obtain the next slot perform 
vag[addi[loc[slot]]], i.e. 



Subrs do not store the names of their arguments. 
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stKargC2;pos] « vag[adclUloc[stk«roCi;pos]]]].^ 



As an example of the use of stknargs and stkarg : 

variablesCpos] returns list of variables bound at pos . 



can be defined by: 



(VARIABLES 
[LAMBDA (POS) 
(PROG (N L) 

(SETO N (STKNARGS PCS)) 
LP (COND 

((ZEROP N) 
(RETURN L))) 
(SETQ L (CONS (COR (STKARG N POS)) 
D) 

(SETQ N (SUBl N)) 
(GO LP]) 



The counterpart of variables is also available. 

stkargs[pos] Returns list of values of variables bound at pos . 

The next three functions, stkscan . evalv . and stkeval all involve searching the 
parameter pushdown stack. For all three functions, £os may be a position on 

7 

the control stack, i.e., a value of stkpos or stknth . In this case, the search 
starts at stkargCstknargs[pos];pos] i.e., it will include the arguments to the 
function at pos but not any locally bound variables. pos may also be a 
position on the parameter stack, in which case the search starts with, and 
includes that position. Finally, £os can be NIL, in which case the search 
starts with the current position on the parameter stack. 



See Section 13 for discussion of vag and loc . 

or a function name, which is equivalent to. stkpos[pos;l] as described 
earlier. 
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stkscanC var ; pos ] 



Searches backward on the parameter stack f roro pos 
for a binding of var. Value is the slot for that 
binding if found, i.e., a parameter stack 
position, otherwise var itself (so that in the 
case of literal atoms, car of stkscan is always 
the value of var ) . 



evalv[var;pos] 



car[stkscan[var;pos]],i.e., returns the value of 
the atom var as of position pos . 



stkevalC pos ; f orm] 



is a more general evalv . It is equivalent to 
evalCform] at position £os, i.e., all variables 



evaluated in form, will be evaluated as of pos . 
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Finally, we have two functions wliich clear the stacks: 



retfron[ pos; value] 



clears the stack back to the function at position 
pos .. and effects a return from that function with 
value as its value. 



reteval[ pos ; f orm] 



clears the stack back to the function at position 
pos ,, then evaluates form and returns with its 
value to the next higher function. In other 
words, retevalC pos, form] is equivalent to 



retf romC pos ; stkevalC pos ; f orm] ] . 
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a 

However, any function^ in form that specifically reference the stack, e.g., 
stkpos , stknth , retf rem , etc., 'see* the stack as it currently is. (See 
page 12.11-13 for descripti n of how stkeval is implemented.) 

9 

Provided form does not involve any stack functions, as explained in 
footnote 8. 
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We also have: 

niapdlCiDapdlfn;Diap(llpos] starts at position mapdlpos (current if NIL)» and 

applies mapdlfn to the function name at each 
pushdown position, i.e., to stknameCmapdlpos] 
until the top of stack is reached. Value is NIL. 
mapdlpos is updated at each iteration. 

For example, mapdlC ( LANBOA (X) (AND (EXPRP X) (PRINT X}))] will print all exprs 
on the push-down list. 

mapdlC(LANBOA (X) (COND ((6REATERP (STKNARG NAPDLPOS) 2) (PRINT X] will print 
all functions of more than two arguments. 

searchpdlCsrchfn;srchpos] searches the pushdown list starting at position 

srchpos (current if NIL) until it finds a position 
for which srchfn applied to the name of the 
function called at that position is not NIL. Value 
is (NANE . position) if such a position is found, 
otherwise NIL. srchpos is updated at each 
iteration . 

The Pushdown List and Funarg 

The linear scan up the parameter stack for a variable binding can be 
interrupted by a special mark called a skip-blip appearing on the stack in a 
name position (See Figure 12-1). In the value position is a pointer to the 
position on the stack where the search is to be continued. This is what is 
used to make stkeval . page 12.10 work. It is also used by the funarg device 
(Section 11). 

When a funarg is applied, INTERLISP puts a skip-blip on the parameter stack 
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with a pointer to the funarq array, and another skip-blip at the top of the 
funarg array pointing back to the stack. The effect is to nake the stack look 
like it has a patch. The names and values stored in the funarg array will thus 
be seen before those higher on the stack. Similarly, setting a variable whose 
binding is contained in the funarg array will change only the array. Note 
however that as a consequence of this implementation, the same instance of a 
funarg object cannot be used recursively. 
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SECTION 13 
NUMBERS AND ARITHMETIC FUNCTIONS 



13.0 General Comments 

There are three different types of numbers In INTERLISP: small Integers* large 
integers, and floating point numbers.^ Since a large integer or floating point 
number can be (in value) any 36 bit quantity (and vice versa), it is necessary 
to distinguish between those 36 bit quantities that represent large integers or 
floating point numbers, and other INTERLISP pointers. We do this by "boxing" 
the number, which is sort of like a special "cons": when a large integer or 
floating point number is created (via an arithmetic operation or by read ). 
INTERLISP gets a new word from "number storage" and puts the large integer or 
floating point number into that word. INTERLISP then passes around the pointer 
to that word, i.e., the "boxed number", rather than the actual 36 bit quantity 
itself. Then when a numeric function needs the actual numeric quantity, it 
performs the extra level of addressing to obtain the "value" of the number. 
This latter process is called "unboxing". Note that unboxing does not use any 
storage p but that each boxing operation uses one new word of number storage. 
Thus, if a computation creates many large integers or floating point numbers, 
i.e., does lots of boxes, it may cause a garbage collection of large integer 
space, GC: 18, or of floating point number space, 6C: 16. 



Floating point numbers are created by the read program when a . or an E 
appears in a number, e.g. 1000 is an integer, 1000. a floating point 
number, as are 1E3 and 1.E3. Note that 10000, lOOOF, and 1E30 are perfectly 
legal literal atoms. 
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13.1 Integer Arithmetic 



Small Integers 

Small integers are those integers for which smallp is true, currently integers 
whose absolute value is less than 1536. Small integers are boxed by offsetting 
them by a constant so that they overlay an area of INTERLISP's address space 
that does not correspond to any INTERLISP data typo. Thus boxing small numbers 
does not use any storage, and furthermore, each small number has a unique 
representation, so that eg may be used to check equality. Note that e^ should 
not be used for large integers or floating point numbers, e.g.» 
eq[2000;addl[1999]] is NIL! e^B. or equal must be used instead. 

Integer Functions 

All of the functions described below work on integers. Unless specified 
otherwise, if given a floating point number, they first convert the number to 
an integer by truncating the fractional bits, e.g., iplus[2.3;3.83s5; if given 
a non-numeric argument, they generate an error, NON-NUMERIC ARG. 

It is important to use the integer arithmetic functions, whenever possible, in 
place of the more general arithmetic functions which allow mixed floating point 
and integer arithmetic, e.g., ip]tus vs plus , igreaterp vs greater p , because the 
integer functions compile open, and therefore run faster than the general 
arithmetic functions, and because the compiler is "smart" about eliminating 
unnecessary boxing and unboxing. Thus, the expression 

(IPLUS (IQUOTIENT (ITIMES N 100) M) (ITIMES X Y)) will compile to perform only 
one box, the outer one, and the expression 

(IGREATERP (IPLUS X Y) (lOIFFERENCE A B)) will compile to do no boxing at all. 
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NotQ that th9 POP- 10 H • 36 bit Bachlnf. so that all integers are between 
-2t35 and 2t35-l.^ Adding two integers which produce a result outside this 
range causes overflow, e.g., 2t34 ••• 2t34. 

The procedure on overflow is to return the largest possible integer, i.e. 
2t35 - 1.^ 



iplus[X|;x2;.. .;x^] 



X J ^ Xjj • ♦ • X|| 



iRiinusCx] 



- X 



ldifference[x;yl 



X - y 



addlCx] 



X 1 



subl[x] 



X - 1 



itines[X| ;X2; . . . ;X||] the product of X|»X2*"*^ 



iquotient[x;y] 



x/y truncated, e.g., iquotlentC3;23"l, 

iquotient[-3,2]s-l 



ireRialnder[x;y] 



the remainder when x is divided by e.g., 
Iremainder [3;2]*1 



igreaterp[x;y] 



T if X > y; NIL otherwise 



Approximately 34 billion 



3 



If the overflow occurs by trying to create a negative number of too large a 
magnitude, -2t35 is used Instead of 2t35-l. 
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ilessp[x;y] 



T is X < y; NIL otherwise 



zerop[x] 



defined as eq[x;0]. 



Note that zerop should not be used for floating point numbers because it uses 
eg. Use eqp[XfOJ instead. 



minuspCx] 



T if x is negative; NIL otherwise. Does not 
convert x to an integer, but simply checks sign 
bit. 



eqp[n;m] 



T if n and ro are or equal numbers, NIL 

otherwise, (eg may be used if n and m are known 
to be small integers.) e^ does not convert n and 
m to integers, e.g., eqp[2000;2000.3>NIL, but it 
can be used to compare an integer and a floating 
point number, e.g., eqp[2000;2000.0]sT. eqp does 
not generate an error if n or m are not numbers. 



smallp[n] 



T if n is a small integer, else NIL. smallp does 
not generate an error if n is not a number. 



fixp[x] 



X if X is an integer, else NIL. Does not generate 
an error if x is not a number. 



fix[x] 



Converts x to an integer by truncating fractional 
bits, e.g., fix[2.3] • 2, fix[-1.7] » -1. If x is 
alrciady an integer, flx[x>x and doesn't use any 
storage . 



Since FIX is also a llspx command (Section 22), typing FIX directly to 
lispx will not cause the function fix to be called. 
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logand[X|;x2; . . . ;X||] lambda no-spr«ad» value is logical and of all its 

argunantSy as an integer, e.g., logandC7;5;6]s4. 

logor[X|;x2; . . . ;X|^] lambda no-spread, value is the logical or of all 

its arguments, as an integer, e.g., 
logor[l;3;9]all. 

logxor[x^;x2; . . . ;X||] lambda no-spread, value is the logical exclusive 

or of its arguments, as an integer, e.g., 
logxorCll;5] ■ 14, 
logxor[ll;5;9] > logxorC14;9] ■ 7. 



lsh[n;m] (arithmetic) left shift, value is n*2tm,i.e., n is 

shifted left ro places, n can be positive or 
negative. If m is negative, n is shifted right -m 
places. 

rsh[n;iD] (arithmetic) right shift, value is n*2t-ffl, i.e., n 

is shifted right m places, n can be positive or 
negative. If m is negative, n is le/t -m places. 

llshCn;n] logical left shift. On PDP-10, llsh is equivalent 

to Ish. 

lrsh[n;m] logical right shift. 

The difference between a logical and arithmetic right shift lies in the 
treatment of the sign bit for negative numbers. For arithmetic right shifting 
of negative numbers, the sign bit is propagated, i.e., the value is a negative 
number. For logical right shift, zeroes are propagated. Note that shifting 
(arithmetic) a negative number 'all the way' to the right yields -1, not 0. 
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13.2 Floating Point Arithmetic 



All of the functions described below work on floating point numbers. Unless 
specified otherwise, if given an integer, they first convert the number to a 
floating point number, e.g., fplus[l;2.3] « fplusCl .0;2.3] « 3.3; if given a 
non-numeric argument, they generate an error, NON-NUMERIC ARG. 

The largest floating point number is 1.7014118E36, the smallest positive (non- 
zero) floating point number is 1 .4693679E-39. The procedure on overflow is the 
same as for integer arithmetic. For underflow, i.e. trying to create a number 
of too small a magnitude, the value will be 0. 

fplusCxj-.x^; . . .Xj^] Xj * Xg ♦ ... ♦ 

fminus[x] - x 

ftimes[Xj jx^; . . . ;X|j] Xj * x^ • . . . • x^^ 

fquotient[x;y] x/y 

f remainderCx;y] the remainder when x is divided by jr, e.g.. 



fremainder[1.0;3.0]s 3.72529E-9. 



ininuspCx] 



T if X is negative; NIL otherwise. W^rks for both 



integers and floating point numbers. 



oqpCx;y] 



T if X and ^ are e£, or equal numbers. See 



discussion page 13.4. 



ffltpCxjyJ 



T if X > y, NIL otherwise. 
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floatp[x] 



is X If X is a floating point number; NIL 
otherwist. Dots not oive an error if x is not a 
number. 



ifote that if number pIx] i& true, then either fixp[xj or floatp[xJ is true. 



floatCx] 



Converts x to a floating point number, e.g.* 
floatCO] « 0.0. 



13.3 Mixed Arithmetic 

The functions in this section are 'contagious floating point arithmetic* 
functions, i.e.» if any of the arguments are. floating point numbers, they act 
exactly like floating point functions, and float all arguments, and return a 
floating point number as their value. Otherwise, they act like the integer 
functions. If given a non-numeric argument, they generate an error, 
NON-NUMERIC ARG. 



Xj ^ ^2 ^ • • • Xgj 



minus[x] 



- X 



dif ferenceCx;y] 



X - y 



times[X| ix^i • • • ;Xj^2 



Xj • Xg • ... « x„ 



quotient[x;yl 



if x and ^ <tre both integers, value is 
iquotient[x;y], otherwise fquotient[x;y]. 



reroainder[x;y] 



if X and £ are both integers, value is 
iremainder[x;y], otherwise fremainderCx;y]. 
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greaterp[x;y] T if x > y, NIL otherwise. 

lessp[x;y] T if x < y, NIL otherwise. 

abs[x] X if X > 0, otherwise -x. abs uses greaterp and 

mlnius, (not igreaterp and iminus ). 



13.4 Special Functions 

These functions are all "borrowed" from the FORTRAN library and handcoded in 
INTERLISP via ASSEMBLE by J. W. Goodwin. They utilize a power series expansion 
and their values are (supposed to be) 27 bits accurate, e.g., sin[30]s.5 
exactly. 



expt[D;n] 



value is ntn. If n is an integer and n is a 
positive integer, vulue is an integer, e.g, 
expt[3;43B81, otherwise the value is a floating 
point number. If m is negative and n fractional, 
an error is generated. 



sqrt[n] 



value is a square root of n as a floating point 
numtier. n nay be fixed or floating point. 
Generates an error if n is negative. sqrt[n] is 
about twice as fast as expt[n;.S] 



log[x] 



value is natural logarithm of x as a floating 
point number, x can be integer or floating point. 



antilogCx] 



value is floating point number whose logarithm is 
x. x can be integer or floating point, e.g., 
antilogCi] • e « 2.71828... 
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sin[x;radiansflo] 



cos[x;radiansflg] 
tan[x;radlansflg] 
arcsinCx;radiansflg] 



arccos[ x ; radlansf Ig ] 
arc tan[ x ; radlansf Ig ] 
randC lower ; upper ] 



X In degrees unless radlansflg «T« Value is sine of 
x as a floating point number. 

Similar to sin. 

Similar to sin. 

X is a number between -1 and 1 (or an error is 
generated). The value of arcs in is a floating 
point number, and is in degrees unless 
radiansflg «T. In other words, if 
arcsin[x;radiansflg]sz then sin[z; radlansf lg]BX* 
The range of the value of arcsln is -90 to +90 for 
degrees, -n/2 to if/2 for radians. 

Similar to arcsln . Range is 0 to 180, 0 to it. 

Similar to arcsln . Range is 0 to 180, 0 to n. 

ValuBf is a pseudo-random number between lower and 
upper inclusive, i.e. rand can be used to generate 
a sequence of random numbers. If both limits are 
integers, the value of rand is an integer, 
otherwise it is a floating point number. The 
algorithm is completely deterministic, i.e. given 
the same initial state, rand produces the same 
sequence of values. The internal state of rand is 
initialized using the function randset described 
below, and Is stored on the free variable 
randstate. 
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randsetCx] 



Value is internal state of rand after randset has 



finished operating, as a dotted pair of two 



intiBgers. If X'NIL, value is current state. If 
xsT, randstate is initialized using the clocks. 
Otherwise, x is interpreted as a previous internal 



state, i.e. a value of randset, and is used to 



reset randstate. For example, 



1. 



(SETQ OLDSTATE (RANDSET)) 



Use rand to generate some random numbers. 



3. 



(RANDSET OLDSTATE) 



4. 



rand will generate same sequence as in 2. 



13.5 Reusing Boxed Numbers - SETN 

rplaca and rplacd provide a way of cannibalizing list structure for reuse in 
order to avoid making new structure and causing garbage collections.^ This 
section describes an analogous function for large Integers and floating point 
numbers, setn . setn is used like setq . i.e., its first argument is considered 
as quoted, its second is evaluated. If the current value of the variable being 
set is a large integer or floating point number, the new value is deposited 
into that word in number storage, i.e., no new storage is used. If the current 
value is not a large integer or floating point number, e.g., it can be NIL, 
setn operates exactly like setq . i.e., the large integer or floating point 
number is boxed, and the variable is set. This eliminates initialization of 
the variable. 



this technique is frowned upon except in well-defined, localized situations 
where efficiency is paramount. 

The second argument to setn must always be a number or a NON-NUMERIC AR6 
error is generated. 
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setn will work interprttively, i.t., reus« a word in number storage, but will 
not yield any savings of storage because the boxing of the second argument will 
still take place, when it is evaluated. The elimination of a box is achieved 
only when the call to setn is compiled, since setn compiles open, and does not 
perform the box if the old value of the variable can be reused. 

Caveats concerning use of SETN 

There are three situations to watch but for when using setn . The first occurs 
when the same variable is being used for floating point numbers and large 
integers. If the current value of the variable is a floating point number, and 
it is reset to a large integer, via setn, the large integer is simply deposited 
into a word in floating point number storage, and hence will be interpreted as 
a floating point number. Thus, 

*-(SETQ FOO 2.3) 
2.3 

♦-(SETN FOO 10000) 
2.189529E-43 

Similarly, if the current value is a large integer, and the new value is a 
floating point number, equally strange results occur. 

The second situation occurs when a setn variable is reset from a large Integer 
to a small integer. In this case, the small integer is simply deposited into 
large integer storage. It will then print correctly, and function 
arithmetically correctly, but it is not a small integer, and hence will not be 
eg to another integer of the same value, e.g., 
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-(SETQ FOO 10000) 
10000 

-(SETN FOO 1) 
1 

MIPLUS FOO 5) 
6 

-(EO FOO 1) 
NIL 

-(SMALLP FOO) 
NIL 

In particular, note that zerop will return NIL even if the variable is equal to 
0. Thus a program which begins with FOO set to a large integer and counts it 
down by (SETN FOO (SUBl FOO)) must terminate with (EQP FOO 0), not (ZEROP FOO). 

Finally, the third situation to watch out for occurs when you want to save the 
current value of a setn variable for later use. For example, if FOO is being 
used by setn , and the user wants to save its current value on FIE, 
(SETQ FOO FIE) is not sufficent, since the next setn on FOO will also change 
FIE, because its changes the word in number storage pointed to by FOO, and 
hence pointed to by FIE. The number must be copied, e.g., 
(SETQ FIE (IPLUS FOO)), which sets FIE to a new word in number storage. 

setn[var;x] nlainbda function like setq . var is quoted, x is 

evaluated, and its value must be a number, var 
will be set to this number. If the current value 
of var is a large integer or floating point 
number, that word in number storage is 
cannibalized. The value of setn is the (new) 
value of var . 

13.6 Box and Unbox 

Some applications may require that a user program explicitly perform the boxing 
and unboxing operations that are usually implicit (and invisible) to most 
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programs. The functions that perform these operations are loc and vag 
respectively. For example, if a user program executes a TENEX JSYS using the 
ASSENBLE directive, the value of the ASSENBLE expression will have to be boxed 
to be used arithmetically, e.g., (IPLUS X (LOC (ASSENBLE — ))). It must be 
emphasized that 

Arbitrary unboxed numbers should not be passed around as ordinary values 
because they can cause trouble for the garbage collector. 

For example, suppose the value of x were 150000, and you created (VAG X), and 
this just happened to be an address on the free storage list] The next garbage 
collection could be disastrous. For this reason* the function vag must be used 
with extreme caution when its argument's range is not known. 

One place where vag is safe to use is for performing computations on stack 
positions, which are simply addresses of the corresponding positions (cells) on 
the stack. To treat these addresses 9ls numbers , the program must first box 
them. Conversely, to convert numbers to corresponding stack positions • the 
program must unbox them. Thus, suppose x were the value of stkarg , i.e., x 
corresponds to a position on the parameter stack. To obtain the next position 
on the stack, the program must compute (VAG (AODl (LOC X))). Thus if x were 
#32002,^ (LOC X) would be 32002Q,^ (AOOl (LOC X)) would be 32003Q, 
and (VAG (AODl (LOC X))) would be #32003. 

Note that rather than starting with a number, and unboxing it to obtain its 
numeric quantity, here we started with an address, i.e., a 36 bit quantity, and 



7 

An INTERLISP pointer (address) which does not correspond to the address of 
a list structure, or an atom, or a number, or a string, is printed as #n, n 
given in octal. " 

Q following a number means the numeric quantity is expressed in octal. 
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wishing to treat it as a number, boxed it. For example, loc of an atom* e.g.* 
(LOC (QUOTE FOO)). treats the atom as a 36 bit quantity, and makes a number out 
of it. If the address of the atom FOO were 125000, (LOC (QUOTE FOO)) would be 
125000, i.e. the location of FOO. It is for this reason that the box operation 
is called loc, which is short for location.^ 

Note that FOO does not print as #364110 (125000 in octal) because the print 
routine recognizes that it is an atom, and therefore prints it in a special 
way, i.e. by printing the individual characters that comprise it. Thus 
(VAG 125000) would print as FOO, and mould be in fact FOO. 

loc[x] Makes a number out of x* i«e«t returns the 

location of x. 

vag[x3 The inverse of loc. x must be a number; the value 

of vas, is the unbox of x* 

The compiler eliminates extra vaiQ^s and loc*s for example 
(IPLUS X (LOC (ASSEMBLE -•))) will not box the value of the ASSEMBLE, and then 
unbox it for the addition. 



g 

vag is an abbreviation of value get. 
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SECTION 14 
INPUT/OUTPUT FUNCTIONS 



14.1 Files 

All input/output functions in INTERLISP can specify their source/destination 
file with an optional extra argument which is the name of the file. This file 
must be opened as specified below. If the extra argument is not given (has 
value NIL), the file specified as "primary" for input (output) is used. 
Normally these are both T» for teletype input and output. However, the primary 
input/output file may be changed by 

Sets file as the primary input file. Its value is 
the name of the old primary input file. 

input[] returns current primary input file, which 
is not changed. 

outputCfile] Same as input except operates on primary output 

file. 

Anif file which is made primary must have been previously opened for 
input/output, except for the file r« which is always open. 



The argument name file is used for tutorial purposes only. The arguments 
to all subrs are U» V, and W as described in arqlist . Section 8. 



inputCfile]^ 
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infileCfile] Opens file for input, and sets it as the primary 

input file.^ The value of infile is the previous 
primary input file. If file is already open, same 
as input[file]. Generates a FILE WON'T OPEN error 
if file won't open, e.g., file is already open for 
outiiut. 

outfile[file] Opens file for output, and sets it as the primary 

output file.^ The value of outfile is the previous 
primary output file. If file is already open, 
same as output[file]. Generates a FILE WON'T OPEN 
error if file won't open, e.g., if file is already 
open for input. 

For all input/output functions, file follows the TENEX conventions for file 
names, i.e. file can be prefixed by a directory name enclosed in angle 
brackets, can contain alt-modes or control-F's, and can include suffixes and/or 
version numbers. Consistent with TENEX, when a file is opened for input and no 
version number is given, the highest version number is used. Similarly, when a 
file is opened for output and no version number is given, a new file is created 
with a version number one higher than the highest one currently in use with 
that file name. 

Regardless of the file name given to the INTERLISP function that opened the 



o 

To open file without changing the primary input file, perform 
inputC infileCfile]]. 

3 

To open file without changing the primary output file, perform 
output[outfile[file]]. 
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file, INTERLISP maintains only full TENEX file names^ in its internal table of 
open files and any function whose value is a file nana always returns a full 
file name» e.g. openp[FOO]«FOO. ;3. Whenever a file aroument is given to an i/o 
function, INTERLISP first checks to see if the file is in its internal table. 
If not, INTERLISP executes the appropriate TENEX JSYS to "recognize" the file. 
If TENEX does not successfully recognize the file, a FILE NOT FOUND error is 
generated.^ If TENEX does recognize the file, it returns to INTERLISP the full 
file narae. Then, INTERLISP can continue with the indicated operation. If the 
file is being opened, INTERLISP opens the file and stores its (full) name in 
the file table. If it is being closed, or written to or read from, INTERLISP 
checks its internal table to make sure the file is open, and then executes the 
corresponding operation. 

Note that each time a full file name is not used, INTERLISP must call TENEX to 
recognize the name. Thus if repeated operations are to be performed, it is 
considerably more efficient to obtain the full file name once, e.g. via inf ilep 
or outfilep . Also, note that recognition by TENEX is performed on the user's 
entire directory. Thus, even if only one file is open, say F00.;1, FS 
(F altroode) will not be recognized if the user's directory also contains the 
file FIE.;1. Similarly, it is possible for a file name that was previously 
recognized to become ambiguous. For example, a program performs infileCFOO], 
opening F00.;1, and reads several expressions from FOO. Then the user types 
control-C, creates a F00.;2 and reenters his program. Now a call to read 
giving it FOO as its file argument will generate a FILE NOT OPEN error, because 
TENEX will recognize FOO as FOO. ;2. 

I 

i.e. name, extension, and version, plus directory name if it differs from 
connected directory. 

except for infilep . outfilep and openp . which in this case return NIL. 
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infilepCfile] Returns full file name of file If recognized by 

TENEX, NIL otherwise. The full file name will 
contain a directory field only if the directory 
differs from the currently attached directory. 
Recognition is in input context, i.e. if no 
version number is given, the highest version 
number is returned. 



infilep and out file n do not open any files * or change the primary files t they 
are pure predicates, 

outfilep[file] Similar to infilep . except recognition is in 

output context, i.e. if no version number is 
given, a version number one higher than the 
highest version number is returned. 



closef[file] Closes file. Generates an error, FILE NOT OPEN, 

if file not open. If file is NIL, it attempts to 
close the primary input file if other than 
teletype. Failing that, it attempts to close the 
primary output file if other than teletype. 
Failing both, it returns NIL. If it closes any 
file, it returns the name of that file. If it 
closes either of the primary files, it resets that 
primary file to teletype. 



closeallC] Closes all open files (except T). Value is a list 

of the. files closed. 

openp[file;type] If type sNIL. value is file (full name) if file is 

open either for reading or for writing. Otherwise 
value is NIL. 
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If typo is INPUT or OUTPUT, value is file if open 
for corresponding type, otherwise NIL. If type is 
BOTH, value is file if open for both input and 
output, (See iofile , page 14.6) otherwise NIL. 

Note: the value of openp is NIL if file is not 
recognized, i.e. openp does not generate an error. 

openp[ ] returns a list of all files open for input 
or output, excluding T. 

Addressable Files 

For roost applications, files are read starting at their beginning and 
proceeding sequentially, i.e. the next character read is the one immediately 
following the last character read. Similarly^ files are written sequentially. 
A program need not be aware of the fact that there is a file pointer associated 
with each file that points to the location where the next character is to be 
read from or written to, and that this file pointer is automatically advanced 
after each input or output operation. This section describes a function which 
can be used to reposition the file pointer, thereby allowing a program to treat 
a file as a large block of auxiliary storage which can be access randomly. For 
example, one application might involve writing an expression at the beginning 
of the file, and then reading an expression from a specified point in its 



Random access means that any location is as quickly accessible as ,any 
other. For example, an array is randomly accessible, but a list is not, 
since in order to get to the nth element you have to sequence through the 
first n-1 elements. 
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middle/ 



A file used in this fashion is much like an array in that it has a certain 
number of addressable locations that characters can be put into or taken from. 
However, unlike arrays, files can be enlarged. For example, if the file 
pointer is positioned at the end of a file and anything is written, the file 
"grows." It is also possible to position the file pointer beyond the end of 
file and then to write. ^ Iii this case, the file is enlarged, and a "hole" is 
created, which can later be written into. Note that this enlargement only 
takes place at the end of a file; it is not possible to make more room in the 
middle of a file. In other words, if expression A begins at positon 1000, and 
expression B at 1100, and the program attempts to overwrite A with expression 
C, which is 200 characters long, part of B will be clobbered. 

iofile[file] Opens file for both input and output « Value is 

file. Does not change either primary input or 
primary output. If no version number is given, 
default is same as for infile , i.e. highest 
version number. 

sfptr[f ile;address] Sets file £ointer for file to address .^ Value is 



This particular example requires the file be open for both input and 
output. This can be achieved via the function lof ile described below. 
However, random file input or output can be performed on files that have 
been opened in the usual way by infile or outfile . 

If the program attempts to read beyond the end of file, an END OF FILE 
error occurs. 

TENEX uses byte addressing; the address of a character (byte) is the number 
of characters (bytes) that precede it in the file, i.e., 0 is the address 
of the beginning of the file. However, the user should be careful about 
computing the space needed for an expression, since end-of-line is 
represented as two characters in a file, but nchars only counts it as one. 
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old sotting* address« «l corresponds to the end of 

ni.." 

address «NIL. sfptr returns the current value of 
file pointer without changino it. 

filepos[x;file;start;end;skip;taiiy^ Searches file for x a la strpos (Section 

10). Search begins at start (or if startsNIL, 
the current position of file pointer), and goes to 
end (or if endaWIl, to the end of file ). Value is 
address of start of natch* or NIL if not found. 
skip can be used to specify a character which 
matches any character in the file. If tail is T, 
and the search is successful, the value is the 
address of the first character <r/ter the sequence 
of characters corresponding to x* instead of the 
starting address of the sequence. In either case, 
the file is left so that the next i/o operation 
begins at the address returned as the value of 
filepos. 



Note: if a file is opened for output only, either by outfile, or 
openf[f ile;100000q] (see page 14.8), TENEX assumes that one intends to 
write a new or different file, even if a version number was specified and 
the corresponding file already exists. Thus, sfptr[file;-l] will set the 
file pointer to 0. If a file is opened for both reading and writing, 
either by lofile or openf[f ile;300000q], TENEX assumes that there might be 
material on the file that the user intends to read. Thus, the initial file 
pointer is the beginning of the file, but sfptrCfile;-!] will set it to the 
end of the file. Note that one can also open a file for appending by 
openfCfile;20000q]. In this case, the file pointer right after opening is 
set to the end of the existing file. Thus, a write will automatically add 
material at the end of the file, and an sfptr is unnecessary. 



filepos was written by J.W. Goodwin. 
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Openf 



openfCf ile;x] opeifis file , x is a number whose bits specify the 

access and mode for file , i.e. x corresponds to 
the second argument to the TENEX JSYS OPENF (see 
JSYiS Manual). Value is full name of file * 

openf permits opening a file for read, write, execute, or append, etc. and 
allows specification of byte size, i.e. a byte size of 36 enables reading and 
writing of full words, openf does not affect the primary input or output file 
settings, and does not check whether the file is already open - i.e. the scune 
file can be opened more than once, possibly for different purposes . '^'^ openp 
will woric for files opened with openf . 

The first argument to openf can also be a number, which is then interpreted as 
JFN. This results in a more efficient call to openf . and can be signficant if 
the user is making frequent calls to openf , e.g. switching byte sizes. 

JFN Functions ^^ 

JFN stands for ^ob file number. It is an integral part of the TENEX file 
system and is described in [Murl], and in somewhat more detail in the TENEX 
JSYS manual. The following function can be used to obtain the JFN for an 
already opened file. 

opnJfn[file] returns the JFN for file . If file not open, 

generates a FILE NOT OPEN error. 

The "thawed" bit in x permits opening a file that is already open. 

13 

The JFN functions were written by J. W. Goodwin. 
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Example: to write a byte on a file 



[OEFINEO (BOUT 

(LAMBDA (FILE BYTE) 
(LOG (ASSEMBLE NIL 

(CO (VAG BYTE)) 

(PUSH NP . 1) 

(CQ (VAG (OPNJFN FILE))) 

(POP NP , 2) 

(JSYS 51Q) 

(MOVE 1,2)] 



or to read a byte from a file 



[OEFINEQ (BIN 

(LAMBDA (FILE) 

(LOC (ASSEMBLE NIL 

(CQ (VAG (OPNJFN FILE))) 
(JSYS 500) 
(MOVE 1.2] 



Making BIN and BOUT substitution macros can save boxing and unboxing in 
compiled code. 



The following functions are available for direct manipulation of JFN's: 



gtJfnCf ile;ext;v;flags] sets up a 'long' call to GTJFN (see JSYS manual). 

file is a file name possibly containing control-F 
and/or alt-mode, ext is the default extension, v 
the default version (overriden if file specifies 
extension /vers ion, e.g. F00.COM ;2). flags is as 
described on page 17, section 2 of JSYS manual. 
file and ext may be strings or atoms; v and flags 
must be numbers. Value is JFN, or NIL on errors. 



rlJfnCJfn] releases Jfn. rljfn[-l] releases all JFN's ««hich 

do not specify open files. Value of rljfn is T. 



JfnsC Jfn;ac3] converts J^Tn (a small number) to a file name. ac3 
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is either NIL, meaning fprmat the file name as 
would openp or other INTERLISP file functions, or 
else is a number, meaning format according to JSYS 
manual. The value of jfns is atomic except where 
enough options are specified by ac3 to exceed atom 
size (> 100 characters). In this case, the value 
is returned as a string. 



14.2 Input Functions 

Most of the functions described below have an (optional) argument file which 
specifies the name of the file on which the operatiqn is to take, place. If 
that argument is NIL, the primary input file will b^ used. 

Notet in all INTERLISP symbolic files, end-of-line is indicated by the 
characters carriage-return and line-feed in that order. Accordingly , on input 
from files, INTEiMI$P will skip all line^feeds which immediately follow 
carriage-returns. On input from teletype, INTERLISP will echo a Hne-'feed 
whenever a carriage-return is input. 

For all input functions except r eadc and peekc , when reading from the teletype, 
control-A erases the last character typed in, echoing a \ and the erased 
character. Control-A will not backup beyong the last carriage return. Typing 
control-Q causes INTERLISP to print //^ and clear the input buffer, i.e. erase 
the entire line back to the last carriage-return. When reading from a file, 
and an end of file is encountered, all input functions close the file and 
generate an error, END OF FILE. 



read[f ile;f Ig] Reads one S^expression from file . Atoms are 

delimited by parentheses, brackets, double quotes, 
spaces, and carriage-returns. To input an atom 
which contains one of these syntactic delimiters, 
preceded the delimiter by the escape character X, 
e.g. ABX(C, is the atom AB(C, XX Is the atom X. 



Actually, INTERLISP skips the next character after a carriage-return 
without looking at it at all. 
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strings are delimited by double quotes. To input 
a string containing a double quote or a X, precede 
it by X, e.g. "ABX"C" is the string AB^C. Note 
that X can always be typed even if next character 
is not 'special', e.g- XAXBXC is read as ABC. 

If an atom is interpretable as a number, read will 
create a number, e.g. 1E3 reads as a floating 
point number, 103 as a literal atom, 1.0 as a 
number, 1,0 as a literal atom, etc. Note that an 
integer can be input in octal by terminating it 
' with a Q, e.g^ 17Q and 15 read in as the same 

integer. The setting of radix , page 14.22, 
determines how Integers are printed, i.e. with or 
without Q's. 

When reading fjv>m the teletype, all input is line^buffered to enable the action 
of control-Q.^ Thus no characters are actually seen by the program until a 
carriage-return is typed. However t for reading by read or uread , when a 
matching right parenthesis is encountered, the effect is the same as though a 
carriage return were typed, i.e. tike characters are transmitted. To indicate 
this, IKTERUSP also prints a carriage'teturn line^feed on the teletype, 

f lg «T suppresses the carriage-return normally 
typed by read following a matching right 
parenthesis. (However, the characters are still 
given to read - i.e. the user does not have to 
type the carriage return himself.) 

ratom[file] Reads in one atom from file. Separation of atoms 



16 



Unless controlCT] has been performed (page 14.24) 
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is defined by action of setsepr and setbrk 
described below. X is also an escape character 
for ratom . and the remarks concerning control-A, 
control-Q, and line-buffering also apply. 

If the characters comprising the atom would 
normally be interpreted as a number by read* that 
number is also returned by ratom . Note however 
that ratom takes no special action for " whether 
or not it is a break character, i.e. ratom never 
makes a string . 

The purpose of ratom , rstring , setbrk^ and setsepr is to atlow the user to 
write his own read program without having to resort to reading character by 
character and then calling pac k to make atoms. The function uread (page 
14.15) is available if the user "wants to handle input as read does, i.e. same 
action on parentheses , double quotes ^ square brackets, dot, spaces, and 
carriage-return, but in addition, to split atoms that contain certain 
characters , as specified by setbrk and setsepr . 

rstring[f ile] Reads in one string from file , terminated by next 

break or separator character. Control-A, control*' 
Q, and X have the same effect as with ratom . 

ATote that the break or separator character that terminates a call to ratom or 
rstring is not read by that call, but remains in the buffer to become the first 
character seen by the next reading function that is called. 

ratoms[a;f ile] Calls ratom repeatedly until the atom a is read. 

Returns a list of atoms read, not including a. 

setsepr[lst;flg] Set separator characters. Value is NIL. 

setbrk[lst;flg] Set break characters. Value is NIL. 
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For both setsepr and setbrk , 1st is a list of character codes, fla determines 
the action of setsepr / setbrk as follows: 

NIL clear out old tables and reset. 

0 clear out only those characters in 1st - 
i.e. this provides an unsetsepr and unsetbrk . 

1 add characters in 1st to corresponding table. 

Characters specified by setbrk will delimit atoms, and be returned as separate 
atoms themselves by ratoro.^^ Characters specified by setsepr will be ignored 
and serve only to separate atoms. For example, if $ was a break character and 
] a separator character, the input stream ABC]]OEFSGH]SS would be read by 6 
calls to ratom returning respectively ABC, DEF, S, GH, S, S. 

Note that the action of % is not affected by setsepr or setbrk . To defeat the 
action of X use escaped, as described below. 

The elements of 1st may also be characters e.g. setbrk[(%( X))] has the same 
effect as setbrk[(40 41)]. Note however that the 'characters' 1,2... 9,0 will 
be interpreted as character codes because they are numbers. 

Initially, the break characters are [ ] ( ) and " and the separator characters 
are space, tab, carriage-return, line-feed, end-of-line, and form-feed. (Note 
that . is not a break or separator character.) setbrk[T] sets the break 
characters to their initial settings, and setseprCT] does the same for the 
separator characters. 

getseprC] Value is a list of separator character codes. 



but have no effect whatsoever on the action of read. 
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Value is a list of break character codes. 

If flgsNIL. makes X act like every other 
character. Normal setting is escape[T]. 

The value of escape is the previous setting. 

If X ■ T, ratest returns T if a separator was 
encountered immediately prior to the last atom 
read by ratom . NIL otherwise. 

If X B NIL, ratest returns T if last atom read by 
ratom or read was a break character, NIL 
otherwise. 

If X B 1, ratest returns T if last atom read 
(by read or ratom ) contained a X (as an escape 
character, e.g., XC or XAX6XC), NIL otherwise. 

Reads the next character, including X, etc. 
Value is the character. Action of readc is 
subject to line-buffering, i.e. readc will not 
return a value until the line has been terminated 
even if a character has been typed. Thus, 
control-A and control-Q will have their usual 
effect. If control[T] has been executed (page 
14.24), defeating line-buffering, readc will 
return a value as soon as a character is typed. 
In addition, if control-A or control-Q are typed, 
readc will return them as values. 
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Value is the next character, but does not actually 
read it, i.e. remove it from the buffer. If 
flg«WIL, peekc is not subject to line-buffering, 
i.e. it returns a value as soon as a character has 
been typed. If flg^T, peekc waits until the line 
has been terminated before returning its value. 
This means that control-A and control-Q will be 
able to perform their usual editing functions. 

Value is last character read from file. 

(for user read). Same as read except it uses 
separator and break characters set by setsepr and 
setbrk . This function is useful for reading in 
list structure in the normal way, while splitting 
atoms containing special characters. Thus with 
space a separator character, and break characters 
of ( ) . and ' the input stream (It*S EASY.) is 
read by uread as the list (IT ' S EASY %.) 

Note that ( ) [ ] and " must be included in the 
break characters if uread is to take special 
action on them, i.e. assemble lists and make 
strings . 

f Ifl aT suppresses carriage-return normally typed 
following a matching right parentheses. See page 
14.11. 
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ifotet read , ratom , ratoms , peekc , readc « and uread all wait for input if there 
is none. The only way to'te^t whether or not there is input is to use 
readp . 



readp[f lie] 



Value is T if there is anything in the input 
buffer of file . NIL otherwise (not particularly 
meaningful for file other than T). Note that 
because of line-buffering, readp may return T, 
indicating there is input in the buffer, but read 
may still have to wait. 



readlineC ] 
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reads a line from the teletype, returning it as a 
list. If readpCT] is NIL, readline retiifn^ NIL^ 
otherwise it reads expressions, using read , 
until it encounters either: 



(1) a carriage-return (typed by the user) that is 
not preceded by any spaces, e.g. 
A B 

and readline returns (ABC) 



(2) a list terminating in a in which case 

the list is included in the value of 
readline , e.g. A B (C D] and readline returns 
(A 6 (C D)). 



17 

Readline actually has two arguments for use by the system, but the user 
should consider it as a function of no arguments. 

Actually, readline performs (APPLY* LISPXREAOFN T), as described in Section 
22. lispxreadfn is initially READ. 
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(3) an unmatched right parentheses or right 
square bracket, which is not included in the 
value of readline , e.g. 
ABC] 

readline returns (ABC). 

In the case that one or nore spaces precede a carriage-return, or a list is 
terminated with a ' )*. readline will type *...* and continue reading on the 

10 

next line, e.g. 



A B 

...(0 E F) 
...(X Y 2] 



and readline returns (A B C (0 E F) (X Y Z)). 

skread[ file; rereads tring]^^ is a skip read function. It moves the file 

pointer for file ahead as if one call to read had 
been performed, without paying the storage and 
compute cost to really read in the structure. 
rereadstring is for the case where the user has 
already performed some readc ' s and ratoro 's before 
deciding to skip this expression. In this case, 
rereadstring should be the material already read 
(as a string), and skread operates as though it 



If the user then types another carriage return, the line will terminate 
e.g. 

A B C V 

and readline returns (A B C) 

so 

skread was written by J. W. Goodwin. 
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had seen that material first, thus getting its 
paren-count, double-quote count, etc. set up 
properly. , 

The value of skread is X) if the first thing 
encountered was a closing paren; X] if the read 
terminated on an unbalanced X], ^ i?.e; -one' whith 
also would have closed ,any extant open left 
parens; otherwise the value of skread is NIL. 



14.3 Output Functions 

Most of the functions described below have an (optional) argument file which 
specifies the name of the file on which the operation is to take place* If 
that argument is NIL, the primary output file will be used. 

Notet in all INTERLISP sumbolic files , end-of-line ts indicated by the 
characters carriage-return and line-feed in that order. Unless otherwise 
stated, carriage^return appearing in the description of an output function 
means carriage-return and line-feed, 

prinl[x;f ile] prints x on file . 

prin2[x;file] prints x on file with X's and "'s inserted where 

required for it to read back in properly by read . 

Both prinl and prin2 print lists as well as atoms and strings; prinl is usually 
used only for explicitly printing formatting characters, e.g. 
(PRINl (QUOTE X[)) might be used to print a left square bracket (the X would 
not be printed by prinl ) . prin? . is used for printing S-expressions which can 
then be read back into INTERLISP with read i.e. regular INTERLISP formatting 
characters in atoms will be preceded by X's, e.g. the atom '()' is printed as 
X(X) by prinZ . If radixsB, prin2 prints a 9 after integers but prini does not 
(but both print the integer in octal). 
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prln3[x;file] Prints ^ with X*s and inserted where required 

for it to read back in properly by uread , i.e. 
uses separator and breale characters specified by 
setbrk and setsepr to determine when to insert 
X*s. 

print[x;file] Prints the S-expression x using prinZ ; followed by 

a carriage*return line-feed. Its value is x* 

For all printing functions, pointers other than lists, strings, atoms, or 
numbers, are printed as where M is the octal representation of the address 
of the pointer (regardless of radix), ifote that this uill not read back in 
correctly, i.e., it will read in as the atom *^lif* » 

spaces[n;filel Prints it spaces; its value is NIL. 

terpriCfile] Prints a carriage-return; its value is NIL. 

Printlevel 

The print functions print , print . prinZ . and prin3 are all affected by a level 
parameter set by 

printleveUn] Sets print level to n, value is old setting. 

Initial value is 1000. printlevel[] gives current 
setting. 

The variable n controls the number of unpaired left parentheses which will be 
printed. Below that level, all lists will be printed as &. 

Suppose X = (A (B C (0 (E F) G) H) K). Then if n ' 2, printCx] would print 
(A (B C & H) K), and if n « 3, (A (B C (D & G) H) K), and if n « 0, Just &. 
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If printlevel is negative, the action is similar except that a carriage-return 
is inserted between all occurrences of right parenthesis immediately followed 
by a left parenthesis. 

The printlevel setting can be changed dynamically* even while INTERLISP is 
printing, by typing control-P followed by a number, i.e. a string of digits, 
followed by a period or exclamation point .^^ The printlevel will immediately be 
set to this number. If the print routine, is currently deeper than the new 
level, all unfinished lists above that level will be terminated by " — 
Thus, if a circular or long list of atoms, is being printed out, typing 
control-PO. will cause the list to be terminated. 

If a period is used to terminate the printlevel setting, the printlevel will be 
returned to its previous setting after this printout. If an exclamation point 
is used, the change is permanent and the printlevel is not restored (until it 
is changed again). 

Motet printlevel only affects teietupe output. Output to all other files acts 
as though level is infinite. 



As soon as control-P is typed, INTERLISP clears and saves the input buffer, 
clears the output buffer, rings the bell indicating it has seen the 
control-P, and then waits for input which is terminated by any non-number. 
The input buffer is then restored and the program continues. If the input 
was terminated by other than a period or an exclamation point, it is 
ignored and printing will continue, except that characters cleared from the 
output buffer will have been lost. 



Another way of "turning off" output is to type control-0* which simply 
clears the output buffer, thereby effectively skipping the next (up to) 64 , 
characters. 
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14.4 Input/Output Control Functions 



clearbufCf lle;flg] Clears the input buffer for file . If file is T 

and flj2 T, contents of INTERLISP's line buffer 
and the system buffer are saved (and can be 
obtained via linbuf and sysout described below). 
When either control-D, control-E, control-H, 
control-P, or control-S is typed, INTERLI5P 
automatically dees a clearbufCT;T]. (For control-P 
and control-S, INTERLISP restores the buffer after 
the interaction. See Appendix 3.) 

linbufCflg] if flg«T. value is INTERLISP's line buffer (as a 

string) that was saved at last clearbuf£T;T]. If 
flg«NIL. clears this internal buffer. 

sysbufCflgl same as linbuf for system buffer. 

If both the system buffer and INTERLISP's line buffer are empty, the internal 
buffers associated with linbuf and sysbuf are not changed by a clearbufCT;T]. 

bklinbuf[x] x is « string, bklinbuf sets INTERLISP's line 

buffer to x. If greater than 160 characters, 
first 160 taken. 

bksysbufCx] x is a string, bksysbuf sets system buffer to x. 

The effect is the same as though the user typed x* 

bklinbuf , bksysbuf , linbuf , and sysbuf provide a way of 'undoing' a clearbuf . 
Thus if the user wants to "peek" at various characters in the buffer, he could 
perform clearbuf[TsT], examine the buffers via linbuf and sysbuf . and then put 
them back. 



14.21 



radix[n] 



Resets output radix^^ to |n| with sign indicator 
the sign of n. For example, -9 will print as 
shown with the following radices?; ^ ^ 



radix . printing 

10 -9 
-10 68719476727 
i.e. (2t36-9) 
8 -HQ 
-8 777777777767Q 

Value of radix is its last setting. radix[3 gives 
current setting without changing it. Initial 
setting is 10. 

fltfmtCn] Sets floating format control to n (See TENEX JSYS 

manual for interpretation of n). fltfmtCT] 
specifies free format (see Section 3). Value of 
fltfmt is last setting. fltfmt[ ] returns current 
setting without changing it. Initial setting is 
T. 

linelength[n] Sets the length of the print line for all files. 

Value is the former setting of the line length. 
Vfhenever printing an atom would go beyond the 
length of the. line, a carriage-return is 
automatically inserted first. linelengthC] 
returns current setting. Initial setting is 72. 



Currently, there is no input radix. 
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posit ionC file] 



Gives the column number the next character will be 



read from or printed to. 



e.g. 



after 



a 



carriage-return. 



positlon»0. 



Note 



that 



position! file] is not the same as sfptrCfile] 



which gives the position in the /i£e, not on the 



line. 



Line-buffering and CONTROL 

In INTERL ISP's normal state, characters typed on the teletype (this section 
does not apply in any way to input from a file) are transferred to a line 
buffer. Characters are transmitted from the line buffer to whatever input 
function initiated the request (i.e., read, uread, ratom, rs tring , or readc ) 
only when a carriage-return is typed.^^ Until this time, the user can delete 
characters one at a time from the input buffer by typing control-A. The 
characters are echoed preceded by a \. Or, the user can delete the entire line 
buffer back to the last carriage-return by typing control-Q, in which case 
INTERLISP echoes ##.^^ (If no characters are in the buffer and either control-A 
or control-Q is typed, INTERLISP echoes ##.) 

Note that this line editing is not performed by read or ratom , but by 
INTERLISP, i.e. it does not matter (nor is it necessarily known) which function 



peekc is an exception; it returns the character immediately. 

As mentioned earlier, for calls from read or uread , the characters are also 
transmitted whenever the parentheses count reaches 0. In this case, if the 
second argument to read or uread is NIL, INTERLISP also outputs a carriage - 
return line-feed. 



Typing rubout clears the entire input buffer at the time it is typed, 
whereas the action of control-A and control-Q occurs at the time they are 
read. Rubout can thus be used to clear type-ahead. 
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will ultinately process the characters, only that they are still in the 
INTERLISP input buffer. Note also that it is the function that is currently 
requesting input tha^ . deteroiines whether parentheses counting is observed, e.g. 
if the user executes (PROGN (RATOM) (READ)) and types in A (B C 0) he will have 
to type in the carriage-return following the right parenthesis before any 
action is taken, whereas if he types (PROGN (READ) (READ)) he would not. 
However, once a carriage-return has been typed, the entire line is 'available' 
even if not all of it is processed by the function initiating the request for 
input, i.e. if any characters are 'left over', they will be returned 
immediately on the next request for input. For example, 
(PROGN (RATOH) (READC)) ~ followed by AB carriage-return will perform both 
operations. 

Turning-off Line-buffering 

The function control is available to defeat this line-^buffering. After 
controlCT], characters are returned to the calling function without line- 
buffering as described below. The function that initiates the request for 
input determines how the line is treated: 

1 • read / uread v » 

if the expression being typed is a list, the effect is the same as though 
control were NIL, i.e. line-buffering until carriage-return or matching 
parentheses. If the expression being typed is not a list, it is returned as 
soon as a break or separator character is encountered, «.g« (READ) followed 



An exception to the above occurs when the break or separator character is a 
(f *» or Cv since returning at this point would leave the line buffer in a 
"funny" state. Thus if control is T and (READ) is followed by 'ABC(', the 
ABC will not be read until a carriage-return or matching parentheses Is 
encountered. In this case the user could con>rol-Q the entire line, since 
all of the characters are still in the buffer. 
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by ABC space will immediately return ABC. Control-A and control-Q editing are 
available on those characters still in the buffer. Thus, if a program is 
performing several reads under control[T], and the user types NOW IS THE TIME 
followed by control-Q, he will delete only TINE since the rest of the line has 
already been transmitted to read and processed. 

2. ratom 

characters are returned as soon as a brkak or separator character is 
encountered. Before then, control->A and control-Q may be used as with read , 
e.g. (RATOM) followed by ABCcontrol-Aspace will return AB. (RATON) followed by 
(control-A will return ( and type ## indicating that control-A was attempted 
with nothing in the buffer, since the ( is a break character and would 
therefore already have been read. 

3 . readc / peekc 

the character is returned immediately; no line editing is possible. In 
particular, (REAOC) followed by control-A will read the controI-A, (READC) 
followed by X will read the X. 

control[u] u^T 

usNIL 
usO 

The value of control when usT or NIL is its 
previous line-buffering setting, i.e. T or NIL. 
When usO or 1, its value is its previous echo 
setting, i.e. 0 or 1. 



eliminates INTERLISP's normal line- 
buffering. 

restores line-buffering (normal), 
eliminates echo of character being 
deleted by control-A. 
restores echo (normal). 
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14.5 Special Functions 



sysout[file] Saves the user's private memory on file . Also 

saves the stacics, so that if a program performs a 
sysout . the subsequent sysin will continue from 
that point, e.g. 

(PROGN (SYSOUT (QUOTE FOO)) (PRINT (QUOTE HELLO))) 
will cause HELLO to be printed after 
(SYSIN (QUOTE FOO)) The value of sysout is file 
(full name). A value of NIL indicates the sysout 
was unsuccessful, i.e., either disk or computer 
error, or user's directory was full. 

S us out does not save the state of any open files. 

Whenever the INTERilSP system is reassembled and/or reloaded, old sysout files 
are not compatible . 

sysinCfile] restores the state of INTERLISP from a sysout 

file. Value is listCfile]. If sysin returns NIL, 
there was a problem in reading the file. If the 
file was not found or is incompatible (see note 
above), generates an error, FILE NOT COMPATIBLE. 



Since sysin continues immediately where sysout left off, the only way for a 
program to determine whether it is Just coming back from a sysin or from a 
sysout is to test the ualue of sysout . 



For example, (COND ((LISTP (SYSOUT (QUOTE FOO))) (PRINT (QUOTE HELLO)))) will 
cause HELLO to be printed following the sysin . but not when the sysout was 
performed. 
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14.6 Symbolic File Input 



loadC file ; Idf Ig ; printf Ig ] 



Reads successive S-expressions from file and 
evaluates each as it is read» until it reads 
either NIL, or the single atom STOP. Value is file 
(full name). 



If printflfl »T, load prints the value of each S- 
expression; otherwise it does not. Idf Ig affects 
the operation of define , defineg , rpaq . and rpaqq . 
While load is operating, dfnflg (Section 8) is 
reset to Idflg .^^ Thus, if Idflg aWIL. and a 
function is redefined, a message is printed and 
the old definition saved. If IdflgsT, the old 
definition is simply overwritten. If Idflg sPROP, 
the function definitions are stored on the 
property lists under the property EXPR. If 
Idflg sALLPROP, not only function definitions but 
also variables set by rpaqq and rpaq are stored on 
property lists. 



loadfns[fns;f ile;ldflg3^^ permits selective loading of function definitions. 

fns is a list of function names, a single function 
name, or T, meaning all functions (but no 



28 



29 



30 



Using resetvar (Section 5). dfnflg cannot simply be rebound because it is 
a GLOBAL variable. See Section 16. 

except when the variable has value NOBIND, in which case it is set to the 
indicated value regardless of dfnflg . 



loadfns was written by J.W. Goodwin. 
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variables, property values, etc,)- file can be 
either a compiled or symbolic file, I.e., any file 
th£it can be loaded by load, file is opened and 
sccinned In the manner of load , and every function 
definition found for a function oil fns is 
loaded. The interpretation of Idflg is the same 
as for load. 

loadfns uses skread (page 14.17) and Icsklp (a 
subfunction of recompile ) to skip over undesired 
material on the file, and so it is very efficient. 
The value of loadfns is a list of those functions 
loaded plus a list of those functions not found 
(If any) headed by the atom NOTFOUNO:, e.g., 
(FOO FIE (NOTFOUND: FUH)). 

readf ile[f lie] Reads successive S-expressions from file using 

read until the single atom STOP is read, or an end 
of file encountered. Value is a list of these 
expressions. 



If a compiled definition is loaded, so are all compiler generated 
subf unctions. Note however if fns specifies entries to a block (see 
Section 18) the user must also specify the block Itself. 



14.26 



14.7 Symbolic File Output 



writef ile[x;f ile;datoflg] 



Writes successive 5-expressions from x on file . 
If X is atomic, its value is used. If file is not 
open, it is opened. If the first expression on x 
is the type produced by printdate , or if datefla 
is T, a new date expression is written. If file 
is a list, car[file] is used and the file is left 
opened. Otherwise, when x is finished, a STOP is 
printed on file and it is closed. Value is file . 



PPCx] 



nlambda, nospread function that performs output[Tl 
and then calls prettyprint: PP FOO is equivalent 
to PRETTYPRINT((FOO)); PP(FOO FIE) or (PP FOO FIE) 
is equivalent to PRETTYPRINT((FOO FIE)) . 
Primary output file is restored after printing. 



prettyprint[lst]®^ 



1st is a list of functions (if atomic, its value 
is used). The definitions of the functions are 
printed in a pretty format on the primary output 
file. For example. 



(FACTORIAL 
[LAMBDA (N) 
(COND 

((ZEROP N) 
1) 

(T (ITINES N (FACTORIAL (SUBl N]) 



32 
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The prettyprint package was written by W. Teitelman. 

prettyprint has a second argument that is T when called from prettydef . In 
this case, whenever prettyprint starts a new function, it prints (on the 
teletype) the name of that function if more than 30 seconds (real time) 
have elapsed since the last time it printed the name of a function. 
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Note: prettyprint will operate correctly on functions that are broken , 
broken- in, advised , or have been compiled with their definitions saved on their 
property lists - it prints the original, pristine 'definition, but does hot 
change the current state of the function. If prettyprint is given an atom 
which is not the name of a function, but has a value, it will prettyprint the 
value. Otherwise, prettyprint will perform spelling correction. If all 
fails, prettyprint returns (atom NOT PRINTABLE). 

Conunent Feature 

A facility for annotating INTERLISP functions is provided in prettyprint . Any 
5-expresslon beginning with * is interpreted as a comment and printed in the 
right margin. Example: 

( FACTORIAL 

[LAMBDA (N) (« COMPUTES Nl) 

(COND 

((ZEROP N) (« 0!-l) 

1) 

(T (« RECURSIVE DEFINITION: 

Nt«N*N-ll) 

(ITIMES N (FACTORIAL (SUBl N]) 

These comments actually form a part of the function definition. Accordingly* * 
is defined as an NLAMBDA NOSPREAD function that returns its argument, i.e. it 
is equivalent to quote . When running an interpreted function, * is entered the 
same as any other INTERLISP function. Therefore, comments should only be 
placed where they will not harm the computation, i.e. where a quoted expression 
could be placed. For example, writing 

(ITIMES N (FACTORIAL (SUBl N)) (« RECURSIVE DEFINITION)) in the above function 
would cause an error when ITIMES attempted to multiply N, N-1!, and RECURSIVE. 



except when prettyprint is called from prettydef . 
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For compilation purposes, * is defined as a macro which compiles into no 
instructions. Thus, if you compile a function with comments, and load the 
compiled definition into another system, the extra atom and list structures 
storage required by the comments will be eliminated. This is the way the 
comment feature is intended to be used. For more options, see end of this 
section. 

Comments are designed mainly for documenting listings. Thus when 
prettyprinting to the teletype, comments are suppressed and printed as the 
string **COMMENT«* .^^ 

Prettydef 

prettydef[prettyfns;prettyfile;prettycoms]^^ Used to make symbolic files 

that are suitable for loading which contain 
function definitions, variable settings, property 
lists, et al, in a prettyprint format. 

The arguments are interpreted as follows: 

prettyfns Is a list of function names. 

The functions on the list are prettyprinted 
surrounded by a (DEFINEQ ...) so that they can be 



®^ The value of **comment»«f Ig determines the action. If **comment**f Ig is 
NIL, the comment is printed. Otherwise, the value of *»comment*»f Ig is 
printed, ''^cominent^^f Ig is initially set to " ««COMHENT*« The function 
pp* is provided to prettyprint functions, including their comments, to the 
teletype. operates exactly like 2£ except it first sets »*comment**flg 

to NIL. 

OA 

prettydef actually has two additional arguments for use by the system. 
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loaded with load . If prettyfns is atoinic (the 
preferred usage), its top level v41ue is used as 
the list of function names, and an rpagg ■ will 
also be written which will set that atom to the 
list of functions when the file is loaded. A 
print expression will also be written which 
informs the user of the named atom or list of 
functions when the file is subsequently loaded. 

prettyfile is the name of the file on which the output is to 

be written. 

The following options exist: 
prettyfile sNIL 

The primary output file is used. 

prettyf ile atomic 

The file is opened if not already open, 
and becomes primary output file. File 
is closed at end of prettydef and 
primary output file is restored. 

prettyfile a list 

Car of the list is assumed to be the 
file name, and is opened if not already 
open. The file is left open at end of 
prettydef . 



rpagg and rpag are like setqq and setq . except they set the top level 
value. See Section 5. 
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prettycoms Is a list of commands interpreted as described 

below. If prettycoms is atomic (the preferred 
usage), its top level value is used and an rpaqq 
is written which will set that atom to the list of 
commands when the file is subsequently loaded » 
exactly as with prettyfns . 

These commands are used to save on the output file top level bindings of 
variables* property lists of atoms, miscellaneous I^TERLISP forms to be 
evaluated upon loading, arrays, and advised functions. It also provides for 
evaluation of forms at ouput time. 

The interpretation of each command in the command list is as follows: 

1. if atomic, an rpaqq is written which will restore the top level value of 
this atom when the, file is loaded. 

2. (PROP propname atom^ ... atom^) an appropriate defllst will be written 
' which will restore the value of propname for each atofflj^ when the file is 

loaded. If propname sALL. the values of all user properties (on the 
property list of each atom^) are saved. If propname is a list, defllst *s 
will be written for each property on that list. 

3. (ARRAY atom^ ... atom^), each atom following ARRAY should have an array as 
its value. An appropriate expression will be written which will set the 
atom to an array of exactly the same size, type, and contents upon loading. 



sysprops is a list of properties used by system functions « Only properties 
not on that list are dumped vrtien the ALL option is used. 
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4. (P ... ), each S-expression following P will be printed on the output file, 
and consequently evaluated when the file is loaded. 

5. (E ... ), each form following E will be evaluated at output time, i.e., 
when prettydef reaches this command. 

6. (FNS fnj ...fn^jj), a defineq is written with the definitions of fn^ ... fn^^ 
exactly as though (fn^ ...fOj^) where the first argument to prettydef . For 
example, suppose the user wanted to set some variables or perform some 
computations in a file before defining functions, he would then write the 
definitions using the FNS command instead of the first argument to 
prettydef . 

7. (VARS var^ ... var^), for each var^i^, an expression will be written which 
will set its top level value when the file is loaded. If var ^ is atomic, 
var ^ will be set to the top-level value it had at the time the file was 
prettydefed, i.e. (RPAQQ var^ top-level-value) is written. If var ^^ is 
non-atomic, it is interpreted as (var form). e.g. 
(FOO (APPEND FIE FUM)) or (F(X) (QUOTE (FOOl F002 F(X)3))). In this case the 
expression (RPAQ var form) is written. 

6. (ADVISE fn^ ... fn^^), for each fn^, an appropriate expression will be 
written which will reinstate the function to its advised state when the 
file is loaded. 

9. (ADVICE fn^ ... fn^,), for each fn^, will write a deflist which will put 
the advice back on the property list of the function. The user can then 
use readvise to reactivate the advice. See Section 19. 

10. (BLOCKS blockj ... blodc^^) for each blociCj^, a declare expression will be 
written which the block compile functions interpret as block declarations. 
See Section 18. 
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11. (CONS com^ ... com^), each of the commands com^ ... com^ will be 
interpreted as ^ prettydef command. 

12. (AODVARS (var^ . Istj) ... (var^^ . Ist^^)) For each var^. the effect is the 
same as (RPAQ var^ (UNION Ist^ var^))» i.e. each element of Ist^ not a 
member of var^ (at load time) is added to it. var^ can initially be 
NOBIND, in which case it is first set to NIL. 

13. (USERMACROS atom^ ... atom|^), each atom^ is the name of a user edit macro. 
USERMACROS writes expressions for adding the definitions to usermacros and 
the names to the appropriate spelling lists. (USERNACROS) will save all 
user edit macros. 

14. (IFPROP propname atom^ ... atom^) same as PROP command, except that only 
non-NIL property values are saved. For example, if FOOl has property PROPl 
and PR0P2, F002 has PR0P3, and F003 has property PROPl and PR0P3, 
(IFPROP (PROPl PR0P2 PR0P3) FOOl F002 F003) will save only those 5 property 
values. 

15. (CONPROP propname atom, ... atomn) same as PROP command, except that the 
corresponding def list expression will also be evaluated when the file is 
compiled. Useful for outputting NACROs. 

16. (COMPROP* propname atom, ... atomn), same as COMPROP except that the 
corresponding def list expressions are not copied to the compiled file by 
tcompl , bcompl , recompile , or brecompile . 

17. (PO ...), like P except that the corresponding S-expressions are also 
printed as DECLARE expressions, and thus will be evaluated when the file is 
compiled. In other words, (PO (OEFLIST (QUOTE — ) (QUOTE propname)) is 
essentially equivalent to (COMPROP propname — ). 
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In each of the commands described above, if the atom * follows the command 
type, the form following the i.e., caddr of the command, is evaluated and 
its value used in executing the command, e.g., (FNS « (APPEND FNSl FHSZ)), 
Note that (COMS * form) provides a way of computing what should be done by 
prettydef . 

New prettydef commands can be defined via prettymacros (see page 14.40). If 
prettydef is given a command not one of the above, and not defined on 
prettymacros , it attempts spelling correction^^ using prettycorosplst as a 
spelling list. If successful, the corrected version of prettycoms is written 
(again) on the output file.*^^ If unsuccessful, prettydef generates an error, 
BAD PRETTYCOM. 



dp 

40 
41 



Except for the PROP, IFPROP, CONPROP, and COMPROP* commands, in which case 
the * must follow the property name, e.g., (PROP MACRO * FOOMACROS). 

unless dwimf lg =NIL. See Section 17. 

since at this point, the uncorrected prettycoms would already have been 
printed on the output file. When the file is loaded, this will result in 
prettycoms being reset, and a message printed, e.g. (FOOVARS RESET). The 
value of FOOVARS would then be the corrected version. 
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Example : 



-SET(FOOFNS (FOOl F002 F003)) 

«-SET(FOOVARS(FIE (PROP MACRO FOOl F002) <P (NOVO (QUOTE FOOl) 

(QUOTE FIEl] 
♦•PRETTYDEF(FOOFNS FOO FOOVARS) 

would create a file FOO containing 

1. A message which prints the time and date the file was made (done 

automatically) 

2. DEFINEQ followed by the definitions of FOOl, F002, and F003 

3. (PRINT (QUOTE FOOFNS) T) 

4. (RPAQQ FOOFNS (FOOl F003 F003)) 

5. (PRINT (QUOTE FOOVARS) T) 

6. (RPAQQ FOOVARS (FIE ...) 

7. (RPAQQ FIE value of fie ) 

8. (DEFLIST (QUOTE ((FOOl propvalue) (F002 propvalue))) (QUOTE MACRO)) 

9. (MOVD (QUOTE FOOl) (QUOTE FIEl)) 

10. STOP 

printfnsCx] x is a list of functions, printfns prints defineq 

and prettyprints the functions. Used by 
prettydef . i.e. command (FNS * FOO) is equivalent 
to conmand (E (PRINTFNS FOO)). 

printdate[file;changes] prints the expression at beginning of prettydefed 

files that upon loading types the time and date 
the file was made, and stores this time and date 
on the property list of file under the property 
FILEDATE. changes is for use by the file package. 



tabCpos;minspaces;f ile] performs appropriate number of spaces to move to 
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position £05. roinspaces indicates the minimuni 
number of spaces to be printed by tab , i.e., it is 
intended to be small number (if NIL, 1 is used). 
Thus, if position minspaces is greater than pos , 
tab does a terpri and then spacesCpos]. 

endfile[file] Prints STOP on file and closes it. 

printdef[expr;left;def ] priints the expression expr on the primary output 

file in a pretty format, left is the left hand 
margin ( linelength determines the right hand 
margin). 2 is used if leftsNIL. 

defiiT means expr is a function definition, or a 
piece of one, i.e. prettyprint is essentially 
printdef[getd[fn];NIL;T]. If defaNIL. no special 
action will be taken for LAMBDA'S, PROG's, COND's, 
comments, CLISP, etc. def is NIL when prettydef 
calls prettyprint to print variables and property 
lists, and when prlntdef is called from the editor 
via the command PPV. 

Special Prettyprint Controls 

All variables described below, i.e., #rpars , firstcol, et al, are globalvars , 
see Section 18. Therefore, if they are to be changed, they must be reset, not 
rebound. 

#rpars controls the number of right parentheses necessary 

for square bracketing to occur. If #rpars «NIL. no 
brackets are used. #rpars is initialized to 4. 
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linelengthCn] 



detennines the position of the right margin for 
prettyprlnt . 



f irstcol 



is the starting column for conunents. Initial 
settinig is 48. Comments run between firstcol and 
linelepgth . If a word in a comment ends with a 
' . ' ahd is not on the list abbrevlst , and the 
position is greater than halfway between firstcol 
and Ijinelength , the next word in the comment 
begins on a new line. Also, if a list is 
encounjtered in a comment » and the position is 
greater than halfway, the list begins on a new 
line, i 



prettylcom 



widepaperCf Ig] 



If a comment is bigger (using count ) than 
prettylcom in size, it is printed starting at 



column 



10, instead of firstcol . prettylcom is 



initialized to 14 (arrived at empirically). 



widepai)er[T] sets linelength to 120, firstcol to 
80 and prettylcom to 28. This is a useful setting 
for prettyprinting files to be listed on wide 
paper. widepaper[] restores these parameters to 
their initial values. The value of widepaper is 
its previous setting. 



commentf Ig 



If car of an expression is e^ to commentf Ig . the 
expression is treated as a comment, commentflg is 
initialized to «. 



prettyf Ig 



If prettyf Ig is NIL, printdef uses prin2 instead 
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of prettyprinting. This is useful for producing a 
fast symbolic dump (e.g. when TENEX is very slow.) 
Note that the file loads the same as if it were 
prettyprinted. prettyflg is initially set to T. 

clispifyprettyflg if T, causes prettyprint to clispify each function 

definition before printing. See Section 23. 
clispifyprettyflg is initially NIL. 

prettymacros Is an assoc-type list for defining substitution 

macros for prettydef . If (FOO (X Y) . corns) 
appears on prettymacros , then (FOO A B) appearing 
in the third argument to prettydef will cause A to 
be substituted for X and B for Y throughout corns 
(i.e., cddr of the macro), and then corns treated 
as a list of commands for prettydef . 

(* E x) A comment of this form causes x to be evaluated at 

prettyprint time, e.g., (* E (RADIX 8)) as a 
comment in a function containing octal numbers can 
be used to change the radix to produce more 
readable printout. The comment is also printed. 



Converting Comments to Lower Case 

This section is for users operating on terminals without lower case who 
nevertheless would like their comments to be converted to lower case for more 
readable line-printer listings. Users with lower-case terminals can skip to 
the File Package sections (as they can type comments directly in lower case). 
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%% If the second atom in a comment is XX, the text of 

the comment is converted to lower case so that it 
looks like English instead of LISP (see next 
page). 

The output on the next page illustrates the result of a lower casing operation. 
Before this function was prettydefed . all comments consisted of upper case 
atoms, e.g., the first comment was (« XX INTERPRETS A SINGLE COMMAND). Note 
that comments are converted onlu when they are actually written to a file by 
prettydef . 

The algorithm for conversion to lower case is the following: If the first 
character in an atom is t, do not change the atom (but remove the t). If the 
first character is X, convert the atom to lower case.^^ If the atom^^ is an 
INTERLISP word,^*^ do not change it. Otherwise, convert the atom to lower case. 
Conversion only affects the upper case alphabet, i.e., atoms already converted 
to lower case are not changed if the comment is converted again . When 
converting, the first character in the comment and the first character 
following each period are left capitalized. After conversion, the comment is 
physically modified to be the lower case text minus the XX flag, so that 
conversion is thus only performed once (unless the user edits the comment 
inserting additional upper case text and another XX flag). 



45 

User must type XX as X is the escape character, 
minus any trailing punctuation marks. 

44 

i.e., is a bound or free variable for the function containing the comment, 
or has a top level value, or is a defined function, or has a non-NIL 
property list. 
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(BREAKCOM 

[LAMBDA (BRKCOM BRKFLG) 

(PROG (BRKZ) 
TOP (SELECTQ 
BRKCOM 

[t (RETEVAL (QUOTE BREAKl) 
(QUOTE (ERROR]] 

(GO 



(* Interprets a 
single command. ) 



(OK 



( BREAKCOM 1 BRKEKP BRKCOM 
(BREAKEXIT)) 



( BREAKCOM 1 BRKEXP BRKCOM 
(BREAKEXIT T)) 
(tWGO 



( BREAKCOM 1 BRKEXP BRKCOM 
(BREAKEXIT)) 
(RETURN 



(* Evaluate BRKEXP 
unless already evaluated^ 
print value, and exit.) 
NIL BRKVALUE) 

(* Evaluate BRKEXP, 
unless already evaluated, 
do NOT print value, 
and exit. ) 
BRKVALUE BRKVALUE) 

(* Same as GO except 
never saves evaluation 
on history.) 
T BRKVALUE) 



(* User will type In expression to be evaluated and 
returned as value of BREAK. Otherwise same as GO.) 



(EVAL 



(BREAKCOMl [SETQ BRKZ (COND 

(BRKCOMS (CAR BRKCOMS)) 
(T (LISPXREAD T] 
(QUOTE RETURN) 

NIL NIL (LIST (QUOTE RETURN) 
BRKZ)) 

(BREAKEXIT)) 



(BREAKCOMl BRKEXP BRKCOM) 
(COND 

(BRKFLG (BREAK2) 

(PRINl BRKFN T) 

(PRINl (QUOTE " EVALUATED 



(« Evaluate BRKEXP but 
do not exit from BREAK.) 



T))) 

(SETQ ! VALUE (CAR BRKVALUE)) 



) 



(* For user*s benefit.) 
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Words on Icaselst will always be converted to 
lower case. Icaselst is initialized to contain 
words which are INTERLISP functions but also 
appear frequently in comments as English words, 
e.g. AND, EVERY, GET, GO, LAST, LENGTH, LIST, etc. 
Thus, in the example on the previous page, not was 
writtan as tNOT, and 60 as 1 60 in order that they 
night be left in upper case. 

words on ucaselst (that do not appear on Icaselst ) 
will be left in upper case. ucaselst is 
initialized to NIL. 

abbrevlst is used to distinguish between 
abbreviations and words that end in periods. 
Normally, words that end in periods and occur more 
than halfway to the right margin cause carriage 
returns. Furthermore, during conversion to 
lowercase, words ending in periods, except for 
those on abbrevlst, cause the first character in 
the next word to be capitalized, abbrevlst is 
initialized to the upper and lower case forms of 
ETC. I.E. and E.G. 

value is lower case version of x* If fig is T, 
the first letter is capitalized, e.g. 
l-caseCFOO;T] » Foo, 1-caseCFOO] » foo. If x is a 
string, the value of Incase is also a string, e.g. 
l-caseC"FILE NOT FOUND" ;T] « "File not found". 

Similar to 1-case 
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14.8 File Package 



This section describes a set of functions and conventions for facilitating the 
bookkeeping involved with working in a large system consisting of many sjmibolic 
files and their compiled counterparts. The file package keeps track of which 
files have been in some way modified and need to be dumped, which files have 
been dumped, but still need to be listed and/or recompiled. The functions 
described below comprise a coherent package for eliminating this burden from 
the user. They require that for each file, the first argument to prettydef , 
(if any), be an atom of the form fileFNS, and the third argument, (if any), be 
fileVARS where file is the name of the file, e.g. 
pre t tydef C FOOFNS ; F(X) ; FOOVARS ] .^^ 

The functions load , editf , edit}/, tcompl , recompile , bcompl , brecompile , and 
DWIN interact with the functions and global variables in the file package as 
follows. Whenever load is called, its argument is added to the list f ilelst , 
and the property FILE, value (fileFNS fileVARS), is added to the property list 
of the file name.^^ This property value is used to determine whether or not the 
file has been modified since the last time it was loaded or dumped. Whenever 
the user calls editf and changes a function, filelst is searched to find the 
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The file package was written by W. Teitelman. It can be disabled by 
setting f ilepkgf Ig to NIL. 

file can contain a suffix and/or version number, e.g. 
PRETTY0EF(FOOFNS F00.TEM;3 FOOVARS) is acceptable. The essential point is 
that the FNS and VARS be computable from the name of the file. 



The name added to filelst has the version number and directory field 
removed, if any. fileFNS and fileVARS are constructed using only the name 
field, i.e., if the user performs load[<TEITELMAN>F00.TEM;2], FOO.TEM is 
added to filelst . and (FOOFNS FOOVARS) put on the property list of FOO.TEH. 
If the file was originally made under a different name, fileFNS and 
fileVARS are computed from the original name (which is obtained from the 
expression that printdate puts at the beginning of the file). 
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files^^ containing this function, i.e. the files for which the function was 
either a member of fileFNS, or appeared In a FNS command on fileVARS. When 
(if) such files are found* the name of the function is added, using /nconc , to 
the value of the property FILE for each file. Thus if the user loads the file 
FOO containing definitions for FOOl, F002, and F003, and then edits F002, 
getpCFOO;FILE] will be (FOOFNS FOOVARS F002) following the edit. A similar 
update takes place for calls to editv. 

Whenever the user dumps a file using makefile (described below), the file is 
added to f ilelst (if not already there) and its FILE property is reinitialized 
to (fileFNS fileVARS), indicating that the file is up to date. In addition, 
the file is added to the list notlistedfiles and notcompiledfiles . Whenever 
the user lists a file using listfiles . it is removed from notlistedfiles . 
Similarly, whenever a file is compiled by tcompl , recompile , bcoropl , or 
brecompile , the file is removed from notcompiledfiles . Thus at each point, the 
state of all files can be determined. This information is available to the 
user via the function files? . Similarly, the user can see whether and how each 
particular file has been modified, dump all files that have been modified, list 
all files that have been dumped but not listed, recompile all files that have 
been dumped but not recompiled, or any combination of any or all of the above 
by using one of the function described below. 



If the user has many files, with complex prettydef commands, this procedure 
could be time consuming. Therefore, in the interests of efficiency, what 
really happens is the function name is simply consed onto the front of the 
list changedfnslst t and variable names are consed onto changedvarslst . 
Whenever the user calls files? , cleanup , makefiles , or any other operation 
that actually looks at the FILE property, the function updatefiles is 
called which scans changedfnslst and changedvarslst and moves the 
function/variable names to the appropriate property lists. The user can 
explicitly perform this updating process by calling updatefiles . 
prettytypelst , page 14.50, provides a way of informing updatefiles about 
user-defined types in addition to functions or variables. 
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maKef ile[f ile;options] adds file to fllelst if not already there. Calls 

prettydef [ f ileFNS ; file ; f ileVARS ; NIL ; changes ] 
« and then adds file to notlistedf iles , 

notcompiledfiles .^^ options is a list of options 
or a single option interpreted as follows: 



FAST perforin prettydef with prettyf Ig sNIL 

RC call recompile after prettydef or 

brecompile if there are any ^l^^l^ 
declarations specified in fileVARS. 

C calls tcompl after prettydef or bcompl 

if there are any block declarations 
specified in fileVARS. 

CLISPIFY perform prettydef with 

clispifyprettyf lg =T, causing clispify 
(see Section 23) to be called on each 
function definition before it is 
prettyprinted. 

NOCLISP performs prettydef with prettytranf lg =T, 
causing CLISP translations to be 
printed, if any» in place of the 
corresponding CLISP expression » e.g. 
iterative statement. 



f ileFNS and fileVARS are constructed from the name field only, e.g. 
makef ile[FOO.TEM] will work, changes is cddr of the FILE property, i.e. 
those items that have been changed since the last makefile . prettydef 
merges those changes with those handled in previous calls to makefile , and 
stores the result on the property FILEDATE in the form 
(datel dateZ changes), where datel is the date of the file that was 
originally loaded, date2 the date of the latest version (i.e. this one), 
and changes (the union of) all items that differ in the two files. 
printdate also includes this information in the expression printed at the 
beginning of the file. 
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except for files that do not contain any function definitions or those that 
have on their property list the property FILETYPE with value DON'TCOMPILE. 
Such files are not compiled even when options specifies C or RC, nor are 
they added to notcompiledf lies . 

Including any generated via the CONS command or via a prettymacro. 



Another way to accomplish this is to put on the property list of the file 
under the property FILETYPE the value CLISP. In this case, the compiler 
will also know to dwimify the functions before compiling. 
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LIST calls llstfiles on file . 



For the three compile options, if F or ST is the next option, it will be given 
to the compiler as the answer to the compiler's question LISTING?* e.g. 
Dialiefile[FOO;(C F^LIST)] will dump FOO, then tcompl or bconpl it without 
redefining any functions, and finally list the file. 

The user can indicate that file must be block compiled with other files by 
putting a list of those files on the property list of each file under the 
property FILEGROUP;. For example, EDIT and WEOIT are one such group, OWIN, 
FIX, CLISP, and OWIHIFY another. If file has a FILEGROUP; property, the 
compiler will not be called until all files on this property have been dumped 
that need to be. In the case of recompiling, brecompile will be called with 
coref Ifl sT only if all of the files in the group are currently in core. 

mal^efilesC options; files] For each file on files that has been changed, 

performs makefile[ file; options]. If files s NIL, 
filelst is used, e.g. makefiles[LIST] will make 
and list all files. ^ Value is a list of all files 
that are made. 

listf ilesCf iles] nlambda, nospread function. Uses bksysbuf to load 

system buffer appropriately to list each file on 
files, (if NIL, notlistedf iles is used) followed 



except if the file is a compiled file, a message is printed and the 
makefile not performed. For example, if the user loads FOO.CON and then 
edits FOOVARS, when makefiles is called, the message 

"FOO.COH IS A COHPILEO FILE AND CANNOT BE DUHPEO." is printed. 



In this case, if any functions have been defined or changed that are not 
contained in one of the files on filelst . a message is printed alerting the 
user. 
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by a QUIT command, then calls a lower EXEC via 
subsys (section 21). The EXEC will then read from 
the system buffer, list the files, and QUIT back 
to the program. 

Each file listed is removed from notlistedf iles if 
the listing is completed, e.g. if the user 
control-C's to stop the listing and QUITS. 

coropilefilesC files] nlambda, nospread function. Executes the RC 

option of makefile for each member of files . (If 
filesaNIL, notcompiledfiles is used.) 

files7C] Prints on terminal the names of those files that 

have been modified but not dumped, dumped but not 
listed, dumped but not compiled, plus the names of 
those functions (if any) that are not contained in 
any file. 

cleanupC f iles] nlaimbda, nospread. Dumps, lists, and recompiles 

(or brecompiles ) any and all files on files 
requiring the corresponding operation. If 
files « NIL, filelst is used. Value is NIL. 

tzg: 

Notei if both a compiled and symbolic version 0/ the same file appear on 
filelst , the compiled file is ignored by makefi I es , files? , and cleanup , 

whereis[x] x is either the name of a function or variable. 



i.e. the compiled file has a CON suffix and its fns and vars are the same 
as those of another (symbolic) file on filelst . 
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whereis sweeps through all the files on sysflles 
filelst looking for files that define or set 
x> prints the names of all such files found. 
whereis knows about and expands all prettydef 
commands and prettymacros . 

ifote that whereis requires that the fileFi/S and fUeVAftS of the files be 
available. However, the system fileFIIS and fileVARS are clobbered to 
save space. To get them back, load the file <LISP>FllfS/VAB$. 

f ilefnslstCfile] returns a list of the functions in file , i.e. 

specified by fileFNS and fileVARS. filefnslst 
knows about prettymacros . 

newfile2C name; corns; type] corns is a list of prettydef commands, type is 

usually FNS or VARS but may be BLOCKS, ARRAYS, 
etc. or the name of any other prettydef command. 

name sNIL, newfileZ returns a list of all 
elements of type type , ( filefnslst and bcoropl and 
brecompile use this option.) 

If naroe aT. newfileZ returns T if there are any 
elements- of type type , ( makefile uses this option 
to determine whether the file contains any FNS, 
and therefore should be compiled, and if so, 
whether it contains any BLOCKS, to determine 
whether to call bcompl / brecompile or 
tcompl / recompile . ) 

Otherwise, newfileZ returns T if name is 
"contained" in corns, ( whereis uses newfileZ in 
this way. ) 
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If the user often employs prettymacros , their expansion by the various parts of 
the system that need to interrogate files can result in a large number of 
conses and garbage collections. If the user could inform the file package as 
to what his various prettymacros actually produce, this expansion would not be 
necessary. For example, the user may have a macro called GRAMMARS which dumps 
various property list but no functions. Thus, the file package could ignore 
this command when seeking information about FNS. The user can supply this 
information by putting on the property list of the prettymacro, e.g. GRAMMARS, 
under the property PRETTYTYPE,^^ a function (or LAMBDA expression) of two 
arguments, com and type , where com is a prettydef command, and type is FNS, 
VARS, BLOCKS, etc. The result of applying the function to these arguments 
should be a list of those elements of type type contained in com . For example, 
the function corresponding to GRAMMARS might be 

(LAMBDA(COM TYPE)(AND (EQ (CAR COh) TYPE)(EO TYPE(QUOTE GRAMMARS) ) (COR COM)).^^ 

Currently, the file package knows about two "types": functions and variables. 
As described in footnote on page 14.45, whenver a function or variable is 
changed, it is added to changedfnslst or changedvarslst respectively. 
Updatef iles operates by mapping down f ilelst and using newfileZ to determine if 
the corresponding file contains any of the functions on changedfnslst or 
changedvarslst . The user can tell the file package about other types by adding 
appropriate entries to prettytypelst . Each element of prettytypelst is a list 
of the form (name-of«changedlist type string), where string is optional. For 



If nothing appears on property PRETTYTYPE, the command is expanded as 
before. 

Note that since the function is given the entire command as an argument, 
the same function could be used for several different types. 
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example, prettytypelst is initially ((CHANGEOFNSLST FNS "functions") 

(CHANGEDVARSLST VARS)).^^ If the user adds ( CHANGEDGRANLST GRAMMARS) to 

prettytypelst , then updatefiles will know to move elements on changedgramlst to 

so 

the FILE property for the files that contain them. 



string is supplied, files? will inform the user if any elements remain 
on the changed list after updatefiles has completed. Similarly, makefiles 
will warn the user that some elements of this type are not going to be 
dumped in the event that it could not find the file to which they belonged. 



It is the user's responsibility to see that elements are added to the 
changed list in the first place. 
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CLI5PIFY (makefile option) 14.46 

CLISPIFYPRETTYFL6 (prettydef variable/parameter).. 14.40,46 

CLOSEALL[] SUBR 14.4 

CLOSEFCFILE] SUBR 14.4 

COMMENTFLG (prettydef variable/parameter) 14.39 

comments (in listings) 14.30-31,40 

COMPILEFILESCFILES] ML* 14.48 

COMPROP (prettydef command) 14.35 

COMPROP* (prettydef command) 14.35 

COMS (prettydef command) 14.35 

CONTROLCU] SUBR 14.11,14,23 

control-A 14.10,12,14-15,23,25 

control-D 14.21 

control-E 14.21 

control~F 14.2 

control-H 14.21 

control-O 14.20 

control-P 14.20-21 

control-Q 14.10-12,14-16,23,25 

control-S 14.21 

DECLARE 14.34-35 

DEFLIST[L;PROP] 14.33 

DFNFLG (system variable/parameter) 14.27 

DWIM 14.44 

DWIMIFY[X;L] , A4.A6 

E (prettydef command) 14.34 

E (In a floating point number) 14.11 

E (use in comments) 14.40 

EDITF[X] NL« : 14.44 

EDITV[EDITVX] ML* , 14.44 

END OF FILE (error message) 14.6,10 
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end-of-llne 14.6/10,13,18 

ENDFILE[Y] 14.38 

ESCAPECFLG] SUBR 14.13-14 

escape character 14.10 

EXPR (property name) 14.27 

FAST (makefile option) , 14.46 

fast symbolic dump 14.40 

FILE (property name) 14.44-45 

file names ♦ 14.2-3 

FILE NOT COMPATIBLE (error message) 14.26 

FILE NOT FOUND (error message) 14.3 

FILE NOT OPEN (error message) 14.3-4,8 

file package 14.44-51 

file pointer 14.5-7 

FILE WON'T OPEN (error message) 14.2 

FILECREATED 14.37,44 

FILEDATE (property name) 14.37,46 

fileFNS 14.44,49 

FILEFNSLST[FILE] 14.49 

FILEGROUP (property name) 14.47 

FILELST (file package variable/parameter) 14.44-50 

FILEPKGFLG (file package variable/parameter) .... 14.44 

FILEPOS[X;FILE;START;END;StCIP;TAIL] 14.7 

files 14.1-10 

FILES7C] 14.45,48,51 

FILETYPE (property name) 14.46 

fileVARS 14.44,49 

FIRSTCOL (prettydef variable/parameter) 14.39 

floating point numbers 14.11 

FLTFMT[N] SUBR 14.22 

FNS (prettydef command) 14.34 

form-feed , 14.13 

GETBRK[] SUBR 14.14 

GETSEPRC] SUBR 14.13 

GLOBALVARS (system variable/parameter) 14.27.38 

GTJFN[FILE;EXT;V;FLA6S] 14.9 

IFPROP (prettydef command) 14.35-36 

INFILE[FILE] SUBR 14.2,6 

INFILEPCFILE] SUBR 14.3-4 

INPUTCFILE] SUBR 14.1 

input buffer 14.16,20-21,23-24 

input functions 14.10-18 

input/output 14.1-51 

input/output control functions 14.21-25 

IOFILE[FILE] SUBR 14.6-7 

IS A COMPILED FILE AND CANNOT BE DUMPED. 

(error message) 14.47 

OFN 14.8-10 

0FNSC0FN;AC3] 14.9 

OSYS 14.8-10,22 

L-CASE[X;FLG] 14.43 

LASTCCFILE] SUBR 14.15 

LCASELST (prettydef variable/parameter) 14.43 

LINBUFCFLG] SUBR 14.21 

line buffer 14.21,23 

line-buffering , 14.11-12,14-16,23 

line-feed 14.10,13,18 
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LINELENGTH[N] SUBR 14.22.39 

LISPXREADFN (prog. asst. variable/parameter) .... 14.16 

LIST (mnkeflle option) 14.47 

LISTFILEStFILES] ML* 14.45,47 

literal atoms 14.11 

LOAD[FILE;LDFLG;PRINTFLG] ,14.27.44 

L0ADFNS[FNS;FILE;LDFL6] 14.27-28 

lower case 14.43 

lower case comments 14.40-43 

MAKEFILE[FILE;OPTIONS] 14.45-48 

MAKEFILES[OPTIONS;FILES] 14.45,47-48,^1 

margins (for prettyprint) 14.38 

NCHARSCX] SUBR 14.6 

NEWFILE2[NAME;C0MS;TYPE;UPDATEFLG] 14.49-SO 

NOBIND 14.27 

NOCLISP (makefile option) 14.46 

(NOT PRINTABLE) 14.30 

NOTCOMPILEDFILES (file package variable/parameter) 14.45-46.48 

NOTLISTEDFILES (file package variable/parameter).. 14.45-48 

numbers 14.11-12 

octal 14.11,18 

OPENF[FILE;X] SUBR 14.8 

opening files 14.1 

OPENP[FILE;TYPE] SUBR 14.3-5,8 

OPNJFN[FILE] SUBR 14.8 

0UTFILE[FILE3 SUBR 14.2,6-7 

OUTFILEP[FILE] SUBR 14.3-4 

OUTPUTCFILE] SUBR 14.1 

output buffer 14.20 

output functions 14.18-20 

P (prettydef command) 14.34 

parentheses counting (by READ) 14.11,23-24 

PD (prettydef command) 14.35 

PEEKCCFILE] SUBR 14.15.25 

POSITION[FILE] SUBR 14.23 

PP[X] ML* 14.29 

PP*[X] NL« 14.31 

PPV (edit command) 14.38 

PRETTYCOMSPLST (prettydef variable/parameter) ... 14.36 
PRETTYDEF[PRETTYFNS;PRETTYFILE;PRETTYCOMS; 

RECOMPILEFLG;CHANGES] 14.31-38.40,44,46 

prettydef commands 14.33-37 

PRETTYFLG (prettydef variable/parameter) 14.39-40,46 

PRETTYLCOM (prettydef variable/parameter) 14.39 

PRETTYMACROS (prettydef variable/parameter) 14.36.40,49-50 

PRETTYPRINT[FNS;PRETTYDEFLG] 14.29 

PRETTYTRANFLG (clisp variable/parameter) 14.46 

PRETTYTYPE (property name) 14.50 

PRETTYTYPELST (file package variable/parameter) . 14.45.50 

primary input file 14.1-2,4,10 

primary output file 14.1,4,18 

PRIN1[X;FILE] SUBR 14.18-19 

PRIN2[X;FILE] SUBR 14.18-19 

PRIN3[X;FILE] SUBR 14.19 

PRINT[X;FILE] SUBR 14.19 

PRINTDATE[FILE;CHANGES] 14.29.37.44,46 

PRINTDEFCEXPR;LEFT;OEF] 14.38-39 
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PRINTFNS[X] 14.37 

printlevel 14.19-20 

PRINTLEVEL[N] SUBR 14.19 

PROP (prettydef command) 14.33,36 

Q (following a number) 14.11,18,22 

QUIT (tenex command) 14.48 

RADIXtN] SUBR 14.11,18,22 

RATESTCX] SUBR 14.14 

RATOMCFILE] SUBR 14.11-13,25 

RATOMSCA;FN] . , 14. 12 

RC (makefile option) 14.46 

READ[FILE;FLG3 SUBR 14.10-11.24 

READC[FILE] SUBR 14.14,25 

READFILE[FILE] 14.28 

READLINE[ LINE ; LISPXFLG] 14 . 16-17 

READP[FILE] SUBR 14.16 

READVISE[X] NL* 14.34 

RECOMPILE[PFILE;CFILE;FNS;COREFLG] 14.44,46,48 

(REDEFINED) (typed by system) 14.27 

RLJFN[JFN] 14.9 

RPAQ[RPAOX;RPAQY] NL 14.27,32 

RPAQQ[X;Y] NL 14.27.32-33 

RSTRING[] SUBR , 14.12 

rubout 14 .23 

searching files 14.7 

separator characters 14.12-15,19.24 

SETBRK[LST;FLG] SUBR 14.12-13,15,19 

SETSEPR[LST;FLG] SUBR 14.12-13,15,19 

SFPTR[FILE;ADDRESS] SUBR 14.6-7,23 

SKREAD[FILE;REREADSTRING] 14.17-18,28 

space 14.13 

SPACES[N;FILE] SUBR 14.19 

square brackets (inserted by prettyprint) 14.38 

STOP (at the end of a file) 14.27-29,38 

strings ^14.11 

STRP0S[X;Y;START;SKIP;ANCH0R;TAIL3 14.7 

SUBSYSC FILE/FORK ; INCOMFILE ;0UTC0HFILE ; 

ENTRYPOINTFLG] 14.48 

symbolic file input 14.27-28 

symbolic file output 14.29-38 

SYSBUF[FLG] SUBR 14.21 

SYSFILES (system variable/parameter) 14.49 

SYSIN[FILE] SUBR 14.26 

SYS0UT[FILE] EXPR 14.21,26 

SYSPROPS (prettydef variable/parameter) 14.33 

tab 14.13 

TAB[P0S;MINSPACES;FILE3 14.37 

TCOMPLCFILES] 14.44,46 

teletype 14.1,4,10-11,16,20,23. 

31 

TENEX 14.2-4,6-8,40 

TERPRICFILE] SUBR 14.19 

U-CASECX] 14.43 

UCASELST (prettydef variable/parameter) 14.43 

UPDATEFILESC ] 14.45, 50-51 

UREAD[FILE;FLG3 SUBR 14.11-12,15,24 

USERNACROS (editor variable/parameter) 14.35 
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USERMACROS (prettydef command) 14.35 

VARS (prettydef command) 14.34 

version numbers 14.2 

WHERE rS[X] 14.48 

WIDEPAPER[FLG] 14.39 

WRITEFILE[X;FILE;DATEFLG] 14.29 

" 14.11-14,19 

* (followed by a number) 14.19 

## (typed by system) 14.10,23,25 

#RPARS (prettydef variable/parameter) 14.38 

5 (alt-mode) 14.2 

X (escape character) 14.10-14,18-19,25 

X (use In comments) 14.41 

XX (use In comments) 14.41 

6 (typed by system) 14.19 

( 14.13 

) 14.13 

* (use in comments) 14.30,39 

* (use 1n prettydef command) 14.36 

**COMMENT'«* (typed by system) 14.31 

««COMMENT«*FLG (prettydef variable/parameter) ... 14.31 

(typed by system) 14.20 

o 14.13 

... (typed by system) 14.17 

C 14,13 

[,] (inserted by prettyprint) 14.38 

\ (typed by system) 14.10,23 

3 14.13,16 

t (use In comments) 14.41 
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SECTION 15 
DEBUGGING - THE BR^AK PACKAGE 



15.1 Debugging Facilities 

Debugging a collection of LISP functions involves isolating problems within 
particular functions and/or deteminlng when and where incorrect data are being 
generated and transmitted* In the INTERLI5P system* there are three facilities 
which allow the user to (temporarily) modify selected function definitions so 
that he can follow the flow of control in his programs, and obtain this 
debugging information. These three facilities together are called the break 
package. All three redefine functions in terms of a system function » break 1 
described below. 

Break modifies the definition of its argument, a function fn, so that if a 
break condition (defined by the user) is satisfied, the process is halted 
temporarily on a call to fn. The user can then interrogate the state of the 
machine, perform any computation, and continue or return from the call. 

Trace modifies a definition of a function fn so that whenever fn is called, its 
arguments (or some other values specified by the user) are printed. When the 
value of fn is computed it is printed also, ( trace is a special case of 
break). 



The break package was written by W. Teitelman. 
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Breakin allows the user to insert a breakpoint inside an expression defining a 
function. When the breakpoint is reached and if a break condition (defined by 
the user) is satisfied, a temporary halt occurs and the user can again 
investigate the state of the computation. 

The following two examples illustrate these facilities. In the first example, 
the user traces the function factorial , trace redefines factorial so that it 
calls breakl in such a way that it prints some information, in this case the 
arguments and value of factorial , and then goes on with the computation. When 
an error occurs on the fifth recursion, breakl reverts to interactive mode, and 
a full break occurs. The situation is then the same as though the user had 
originally performed BREAK (FACTORIAL) instead of TRACE (FACTOR I AL ) , and the user 
can evaluate various INTERLISP forms and direct the course of the computation. 
In this case, the user examines the variable n, and instructs breakl to return 
1 as the value of this cell to factorial . The rest of the tracing proceeds 
without incident. The user would then presumably edit factorial to change L to 
1. 

In the second example, the user has constructed a non-recursive definition of 
factorial . He uses breakin to insert a call to breakl just after the PROG 
label LOOP. This break is to occur only on the last two iterations, i.e., when 
n is less than 2. When the break occurs, the user looks at the value of n. 
mistakenly typing NN. However, the break is maintained and no damage is done. 
After examining n and m the user allows the computation to continue by typing 
OK. A second break occurs after the next iteration, this time with N^O. When 
this break is released, the function factorial returns its value of 120. 
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♦•PP FACTORIAL 



(FACTORIAL 
[LAMBDA (N) 
(COND 

((ZEROP N 
L) 

(T (ITIMES N (FACTORIAL (SUBl N]) 

FACTORIAL 
*-TRACE( FACTORIAL) 
(FACTORIAL) 
^FACT0RIAL(4) 

FACTORIAL: 
N = 4 

FACTORIAL: 
N » 3 

FACTORIAL: 
N « 2 

FACTORIAL: 
N « 1 

FACTORIAL: 
N « 0 

U.B.A. 
L 

(FACTORIAL BROKEN) 

:N 

0 

: RETURN 1 

FACTORIAL « 1 
FACTORIAL « 1 
FACTORIAL « 2 
FACTORIAL = 6 
FACTORIAL = 24 
24 
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*-PP FACTORIAL 



(FACTORIAL 
[LAMBDA (N) 
(PROG ((M 1)) 
LOOP(COND 

((ZEROP N) 
(RETURN M))) 
(SETQ M (ITIMES M N)) 
(SETQ N (SUBl N)) 
(GO LOOP]) 

FACTORIAL 

-BRFAKIN(FACTORIAL (AFTER LOOP) (ILESSP N 2] 

SEARCHING. . . 

FACTORIAL 

-FACT0RIAL(5) 

((FACTORIAL) BROKEN) 
:NN 

U.B.A. 
NN 

(FACTORIAL BROKEN AFTER LOOP) 
:N 



:M 

120 

:0K 

(FACTORIAL) 

((FACTORIAL) BROKEN) 

:N 

0 

:0K 

(FACTORIAL) 
120 



15.2 Breakl 



The basic function of the break package is breakl . Whenever INTERLISP types a 
message of the form (- BROKEN) followed by the user is then 'talking to' 
breakl , and we say he is 'in a break.' breakl allows the user to interrogate 
the state of the world and affect the course of the computation. It uses the 
prompt character ':' to indicate it is ready to accept input(s) for evaluation, 
in the same way as evalqt uses •♦-', The user may type in an expression for 
evaluation as with evalqt . and the value will be printed out, followed by 
another : . Or the user can type in one of the commands specifically recognized 
by breakl described below. 
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Since breakl puts all of the power of INTERLISP at the user's coinroand» he can 
do anything he can do at evalqt * For example, he can insert new breaks on 
subordinate functions sinply by typing: 

(BREAK fnl fn2 ...) 

or he can remove old breaks and traces if too much information is being 
supplied: 

(UNBREAK fn3 fn4 ...) 
He can edit functions* including the one currently broken: 
EDITF(fn) 

For example, the user might evaluate an expression, see that the value was 
incorrect, call the editor, change the function, and evaluate the expression 
again, all without leaving the break. 

Similarly, the user can prettyprint functions, define new functions or redefine 
old ones, load a file, compile functions, time a computation, etc. In short, 
anything that he can do at the top level can be done while inside of the break. 
In addition the user can examine the pushdown list, via the functions described 
in Section 12, and even force a return back to some higher function via the 
function retf rom or reteval . 

It is important to emphasize that once a break occurs, the user is in complete 
control of the flow of the computation, and the computation will not proceed 
without specific instruction from him. If the user types in an expression 
whose evaluation causes an error, the break is maintained. Similarly if the 
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user aborts a computation initiated from within the break, the break is 
maintained. Only if the user gives one of the commands that exits from the 
break, or evaluates a form which does a ret from or reteval back out of breakl , 
will the computation continue. 

Note that breakl is just another INTERLISP function, not a special system 
feature like the interpreter or the garbage collector. It has arguments which 
are explained later, and returns a value, the same as cons or cond or prog or 
any other function. The value returned by breakl is called 'the value of the 
break.' The user can specify this value explicitly by using the RETURN command 
described below. But in most cases, the value of a is given implicitly, via a 
GO or OK command, and is the result of evaluating 'the break expression,' 
brkexp , which is one of the arguments to breakl . 



The break expression is an expression equivalent to the computation that would 
have taken place had no break occurred. For example, if the user breaks on the 
function FOO, the break expression is the body of the definition of FOO. When 
the user types OK or GO, the body of FOO is evaluated, and its value returned 
as the value of the break, i.e. to whatever function called FOO. The effect is 
the same as though no break had occurred. In other words, one can think of 
breakl as a fancy eval, which permits interaction before and after evaluation. 
The break expression then corresponds to the argument to eval. 



By typing control-E, see Section 16. 



Except that breakl does not 'turn off control-0, i.e. a control-D will 
force an immediate return back to the top level. 
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Releases the break and allows the computation to 
proceed. breakl evaluates brkexp , its first 
argument, prints the value of the break, brkexp 
is set up by the function that created the call to 
breakl ♦ For break or trace , brkexp is equivalent 
to the body of the definition of the broken 
function. For breakin , using BEFORE or AFTER, 
brkexp is NIL. For breakin AROUND, brkexp is the 
indicated expression. See breakin . page 15.19. 



Same as GO except the value of brkexp is not 
printed. 



Same as GO or OK except that the break is 
maintained after the evaluation. The user can 
then interrogate the value of the break which is 
bound on the variable lvalue , and continue with 
the break. Typing GO or OK following EVAL will 
not cause reevaluation but another EVAL will. 
EVAL is a useful command when the user is not sure 
whether or not the break will produce the correct 
value and wishes to be able to do something about 
it if it is wrong. 



The value of the indicated computation is returned 
as the value of the break. 

For example, one might use the EVAL command and 
follow this with RETURN (REVERSE 'VALUE). 



Calls error} and aborts the break, i.e. makes it 
"go away' without returning a value. This is a 
useful way to unwind to a higher level break. All 
other errors, including those encountered while 
executing the GO, OK, EVAL, and RETURN commands, 
maintain the break. 



function is first unbroken, then evaluated, and 
then rebroken. Very useful for dealing with 
recursive functions. 



Function is first unbroken, evaluated, rebroken, 
and then exited, i.e. I OK is equivalent to !EVAL 
followed by OK. 



Function is first unbroken, evaluated, rebroken, 
and exited with value typed, i.e., fEVAL followed 
by GO. 
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unbreaks brkfn , e.g. 

(FOO BROKEN) 

:UB 

FOO 



and FOO is now unbroken 



resets the variable lastpos , which establishes a 
context for the commands ARCS, BT, BTV, BTV*, 
and EDIT, and IN? described below, lastpos is the 
position of a function call on the push-down 
stack. It is initialized to the function Just 
before the call to breakl , i.e. stknth[-l ;BREAK1] 

@ treats the rest of the teletype line as its 
argumont(s). It first resets lastpos to 
stknth[-l;BREAKl] and then for each atom on the 
line, 9 searches backward, for a call to that 
atom. The following atoms are treated specially: 

'§ do not reset lastpos to 

stknthC-l;BREAKl] but leave it as it 
was, and continue searching from that 
point. 



numbers if negative, move lastpos back that 
number of calls, if positive, forward, 
i.e. reset lastpos to stknth[n; lastpos] 

search forward for next atom 

/ the next atom is. a number and can be 

used to specify more than one call e.g. 
0 FOO / 3 is equivalent to 
9 FOO FOO FOO 

Example : 



if the push-down stack looks like 



BREAK 1 


(13) 


FOO 


(12) 


SETQ 


(11) 


COND 


(10) 


PROG 


(9) 


FIE 


(8) 


COND 


(7) 


FIE 


(6) 


COND 


(5) 


FIE 


(4) 


COND 


(3) 


PROG 


(2) 


FUM 


(1) 



then 9 FIE COND will set lastpos to the position 
corresponding to (7); 0 0 COND will then set 
lastpos to (5); © FUM - FIE to (4); and 
9 FIE / 3 -1 to (3). 

If 9 cannot successfully complete a search, it 
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types (fn NOT FOUND), where fn is the narae of the 
function for which it was searching. 

When 9 finishes, it types the name of the function 
at lastpos , i.e. stknaroe[lastpos] 

9 can be used on brkcoms . In this case, the next 
command on brkcoms is treated the same as the rest 
of the teletype line. 



This is a multi-purpose command. Its most common 
use is to interrogate the value(s) of the 
arguments of the broken function, e.g. if FOO has 
three arguments (X Y Z), then typing ?■ to a break 
on FOO, will produce: 

:?» 

X B value of X 

Y s value of Y 

Z a value of Z 



?s operates on the rest of the teletype line as 
its arguments. If the line is empty, as in the 
above case, it prints all of the arguments. If 
the user types ?« X (CAR Y), he will see the value 
of X, and the value of (CAR Y). The difference 
between using ?= and typing X and (CAR Y) directly 
to breakl is that ?s evaluates its inputs as of 
lastpos , i.e. it uses stkeval. This provides a 
way of examing variables or performing 
computations as of a particular point on the 
stack. For example, @ FOO / 2 followed by ?s X 
will allow the user to examine the value of X in 
the previous call to FOO, etc. 

?s also recognizes numbers as refering to the 
correspondingly numbered argument, i.e. it uses 
stkarg in this case. Thus 

:0 FIE 
FIE 
:?= 2 

will print the name and value of the second 
argument of FIE. 

?= can also be used on brkcoms , In which case the 
next command on brkcoms is treated as the rest of 
the teletype line. For example, if brkcoms is 
(EVAL (X Y) GO), brkexp will be evaluated, the 
values of X and Y printed, and then the function 
exited with its value being printed. 



Prints a backtrace of function names only starting 
lastpos . (See discussion of @ above) The 
several nested calls in system packages such as 
break, edit, and the top level executive appear as 
the single entries «*BREAK««, ««EOITOR««, and 
AftTOP** respectively. 
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BTV 



Prints a backtrace of function names with 
variables beginning at lastpos . 



BTV* Same as BTV except also prints arguments of 

internal calls to eval . (See Section 12) 



BTV! Same as BTV except prints everything on stack. 

(See Section 12). 

BT» BTV» BTV*, and BTV! all permit an optional functional argument which is a 
predicate that chooses functions to be skipped on the backtrace, e.g., BT SUBRP 
will skip all SUBRs. BTV (LAMBDA (X) (NOT (MEMB X FOOFNS))) will skip all but 
those functions on FOOFNS. If used as a brkcom the functional argument is no 
longer optional, i.e. the next brkcom must either be the functional argument, 
or NIL if no functional argument is to be applied. 

For BT, BTV, BTV*, and BTV!, if control-P is used to change a printlevel during 
the backtrace, the printlevel will be restored after the backtrace is 
completed. 

ARGS Prints the names of the variables bound at 

lastpos , i.e. variables[ lastpos] (Section 12). 
For most cases, these are the arguments to the 
function entered at that position, i.e. 
arglist[ stknameC las tpos 3 ] . 

The following two commands are for use only with unbound atoms or undefined 
function breaks (see Section 16). 



= form, B fn[args] only for the break following an unbound atom 

error. Sets the atom to the value of the form, or 
function and arguments, exits from the break 
returning that value, and continues the 
computation, e.g. 

U.B.A. 

(FOG BROKEN) 
:= (COPY FIE) 

sets FOO and goes on. 
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-> expr for use either with unbound atom error, or 

undefined function error. Rep^ces the expression 
containing the error with expr (not the value of 
expr ) e.g., 

U.D.F. 

(FOOl BROKEN) 
:-> FOO 

changes the FOOl to FOO and continues the 

computation. 

expr need not be atomic, e.g. 
U.B.A. 

(FOO BROKEN) 
!-> (QUOTE FOO) 

For U.D.F. breaks, the user can specify a function 
and initial arguments, e.g. 

U.D.F. 

(HENBERX BROKEN) 
:-> MEMBER X 

Note that in the case of a U.D.F. error occurring 
immediately following a call to apply , e.g. 
(APPLY X Y) where the value of x is FOO and FOO is 
undefined, or a U.B.A. error immediately following 
a call to eval, e.g. (EVAL X), where the value of 
X is FOO and FOO is unbound, there is no 
expression containing the offending atom. In this 
case, -> cannot operate, so 7 is printed and no 
action taken. 



EDIT designed for use in conjunction with breaks caused 

by errors. Facilitates editing the expression 
causing the break: 

NON-NUMERIC ARC 
NIL 

(IPLUS BROKEN) 

:EOIT 

IN FOO... 

(IPLUS X Z) 

EDIT 

*(3 Y) 

*0K 

FOO 



and user can continue by typing OK, EVAL, etc. 



-> does not change just brkexp ; it changes the function or expression 
containing the erroneous form. In other words, the user does not have to 
perform any additional editing. 
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This command is very simple conceptually, but complicated in its implementation 
by all of the exceptional cases involving inteactions with compiled functions, 
breaks on user functions, error breaks, breaks within breaks, et al. 
Therefore, we shall give the following simplified explanation which will 
account for 90% of the situations arising in actual usage. For those others, 
EDIT will print an appropriate failure message and return to the break. 

EDIT begins by searching up the stack beginning at lastpos (set by 9 command, 
initially position of the break) looking for a form, i.e. an internal call to 
eval . Then EDIT continues from that point looking for a call to an interpreted 
function, or to eval . It then calls the editor on either the EXPR or the 
argument to eval in such a way as to look for an expression e^ to the form that 
it first found. It then prints the form, and permits interactive editing to 
begin. Note that the user can then type successive 0*s to the editor to see 
the chain of superforms for this computation. 

If the user exits from the edit with an OK, the break expression is reset, if 
possible, so that the user can continue with the computation by simply typing 
OK. However, in some situations, the break expression cannot be reset. For 
example, if a compiled function FOO incorrectly called putd and caused the 
error ARG NOT ATOM followed by a break on putd , EDIT might be able to find the 
form headed by FOO, and also find that form in some higher interpreted 
function. But after the user corrected the problem in the FOO-form, if any, he 
would still not have in any way informed EDIT what to do about the immediate 
problem, i.e. the incorrect call to putd . However, if FOO were interpreted 
EDIT would find the putd form Itself, so that when the user corrected that 
form, EDIT could use the new corrected form to reset the break expression. The 
two cases are shown below: 



Evaluating the new brkexp will involve reevaluating the form that causes 
the break, e.g. if (PUTD (QUOTE (FOO)) big-computation) were handled by 
EDIT, big-computation would be reevaluated. 
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ARG NOT ATOM 

(PUTO BROKEN) 

:EOIT 

IN FOO... 

(PUTD X) 

EDIT 

*(2 (CAR X)) 

*0K 

FOO 

:0K 

PUTD 



IN? similar to EDIT, but Just prints parent form, and 

superform, but does not call editor, e.g. 

ATTEMPT TO RPLAC NIL 
T 

(RPLACD BROKEN) 
:IN? 

FOO: (RPLACD X Z) 



Although EDIT and IN? were designed for error breaks, they can also be useful 
for user breaks. For example, if upon reaching a break on his function FOO, 
the user determines that there is a problem in the call to FOO, he can edit the 
calling form and reset the break expression with one operation by using EDIT. 
The following two protocol's with and without the use of EDIT, illustrate this: 



ARG NOT ATOM 

(FUM) 

(PUTD BROKEN) 

tEDIT 

IN FIE... 

(FOO X) 

EDIT 

*(2 (CAR X)) 
«0K 

NOTE: BRKEXP NOT CHANGED 

FIE 
:?^ 

U = (FUM) 

:(SETQ U (CAR U)) 

FUM 

:0K 

PUTD 
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(FOO BROKEN) 

:?= 

X - (A B C) 

Y = D 
:BT 

FOO 

SETQ 

COND 

PROG 

FIE 

:EDITF(FIE) 

EDIT 

«F FOO P 

(FOO V U) 

*(SW 2 3) 

*0K 

FIE 

:(SETQ Y X) 
(A B C) 
:(SETQQ X D) 
D 

:?= 
X = 0 

Y = (A B C) 
:0K 

FOO 



find which function 
FOO is called from 

(aborted with tE) 



edit it 



reset X and Y 



(FOO BROKEN) 

:?= 

X =: (A B C) 

Y = D 

•.EDIT 

IN FIE... 

(FOO V U) 

EDIT 

*(SW 2 3) 
«0K 
FIE 
:0K 
FOO 



0 



check them 



Brkcoms 

The fourth argument to breakl is brkcoms , a list of break commands that breakl 
interprets and executes as though they were teletype input. One can think of 
brkcoms as another input file which always has priority over the teletype. 
Whenever brkcoms =NIL, breakl reads its next command from the teletype. 
Whenever brkcoms is not NIL, break! takes as its next command carC brkcoms] and 
sets brkcoms to cdr[brkcoms]. For example, suppose the user wished to see the 
value of the variable x after a function was evaluated. He would set up a 
break with brkcomss ( EVAL (PRINT X) OK), which would have the desired effect. 
The function trace uses brkcoms : it sets up a break with two commands; the 
first one prints the arguments of the function, or whatever the user specifies, 



X and ;)r have not been changed, but brkexp has. See previous footnote. 
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and the second is the command G0» which causes the function to be evaluated and 
its value printed. 

If brkcoms is not NIL, the value of a break command is not printed. If you 
desire to see a value, you must print it yourself, as in the above example with 
the command (PRINT X). 

Motei wheneuer an err^r occurs » brkcoms is set to HILt oni a full interactive 
break occurs » 

Brkfile 

The break package has a facility for redirecting ouput to a file. The variable 
brkfile should be set to the name of the file, and the file must be opened. 
All output resulting from brkcoms will be output to brkfile , e.g. output due to 
TRACE. Output due to user typein is not affected, and will always go to the 
terminal, brkfile is initially T. 

Breakmacros 

Whenever an atomic command is given breakl that it does not recognize, either 
via brkcoms or the teletype, it searches the list breakmacros for the command. 
The form of breakmacros is ( ... (macro command^ command2 ... command^) ...}. 
If the command is defined as a macro, breakl simply appends its definition, 
which is a sequence of commands, to the front of brkcoms . and goes on. If the 
command is not contained in breakmacros , it is treated as a function or 
variable as before. 

Example: the command ARGS could be defined by including on breakmacros ; 
(ARGS (PRINT (VARIABLES LASTPOS T))). 
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15.3 Break Functions 



break 1[ brkexp ; brkwhen ;brk:fn;brk(:oms;brktype] 

is an n lambda , brkwhen determines whether a break 
is to occur. If its value is NIL, brkexp is 
evaluated and returned as the value of breakl . 
Otherwise a break occurs and an identifying 
message is printed using brkfn . Commands are then 
taken from brkcoros or the teletype and 
interpreted. The commands, GO, !G0, OK, !0K, 
RETURN and t, are the only ways to leave breakl . 
The command EVAL causes brkexp to be evaluated, 
and saves the value on the variable lvalue . Other 
commands can be defined for breakl via 
breakmacros . brktype is NIL for user breaks, 
INTERRUPT for control-H breaks, and ERRORX for 
error breaks. 

For error breaks, the input buffer is cleared and saved. (For control-H 
breaks, the input buffer was cleared at the time the control-H was typed, see 
Section 16.) In both cases, if the break returns a value, i.e., is not aborted 
via t or control-D, the input buffer will be restored (see Section 14). 

breakOC fn ;when ;coms] sets up a break on the function fn by redefining 

jTn as a call to breakl with brkexp an equivalent 
definition of fn, and when, fn, and corns , as 
brkvfhen . brkfn , brkcoms . Puts property BROKEN on 
property list of fn with value a gensym defined 
with the original definition. Puts property 
BRKINFO on property list of jQi with value (BREAKO 
when corns) (For use in conjunction with rebreak ) . 
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Adds fn to the front of the list broKenfns * Value 
is fn. 

If fn is non-atomic and of the form (fnl IN fn2), 
breakO first calls a function which changes the 
name of fnl wherever it appears inside of fn2 to 
that of a new function, fni-IN-fn2, which it 
initially defines as fnl . Then breakO proceeds to 
break on fnl-IN-fn2 exactly as described above. 
This procedure is useful for breaking on a 
function that is called from many places, but 
where one is only interested in the call from a 
specific function, e.g. (RPLACA IN FOO), 
(PRINT IN FIE), etc. It is similar to breakin 
described below, but can be performed even when 
FII2 is compiled or blockcompiled, whereas breakin 
only works on interpreted functions. 

If fnl is not found in fnZ, breakO returns the 
value (fnl NOT FOUND IN fn2}. 

IlLL is found in fn2, in addition to breaking 
fnl-IN-fn2 and adding fnl-IN-fn2 to the list 
brokenfns, breakO adds fnl 'to the property value 
for the property NAMESCHANGED on the property list 
of fn2 and adds the property ALIAS with the value 
(fn2 . fnl) to the property list of fnl-IN-fn2 . 
This will enable unbreak to recognize what changes 
have been made and restore the function fn2 to its 
original state. 
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If fn is nonatomic and not of the above form, 
breakO is called for each member of fn using the 
same values for when , corns , and file specified in 
this call to breakO. This distributivity permits 
the user to specify complicated break conditions 
on several functions without excessive retyping, 

breakOC(F001 ((PRINT PRINl) IN (F002 F003))); 
(NEO X T);(EVAL ?= (Y Z) OK)] 

will break on FOOl, PRINT- IN-F002, PRINT- IN-F003, 
PRIN1-IN'F002 and PRIN1-IN-F003. 

If :[n is non-atomic, the value of breakO is a list 
of the individual values. 

break[x] is a nospread n lambda . For each atomic argument, 

it performs breakO[atom;T]. For each list, it 
performs apply[6REAK0;llst]. For example, 
break[F001 (F002 (GREATERP N 5) (EVAL))] is 
equivalent to breakO[F001,T] and 

breakO[F002; (GREATERP N 5); (EVAL)] 

trace[x] is a nospread nlambda . For each atomic argument, 

it performs breakO[atom;T;( TRACE ?= NIL GO)]^ For 
each list argument, car is the function to be 
traced, and cdr the forms the user wishes to see, 
i.e. trace performs: 

breakOC car[ lis t ] ; T ; list[ TRACE ; 7- ; cdr[ list ] , GO] ] 



The flag TRACE is checked for in breakl and causes the message 'function 
to be printed instead of (function BROKEN). 
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For exanple, TRACE(F001 (F002 Y)) will cause both 
FOOl and F002 to be traced. All the arguments of 
FOOl will be printed; only the value of Y will be 
printed for F002. In the special case that the 
user wants to see only the value, he can perform 
TRACE((fn)). This sets up a break with commands 
<TRACE ?• (NIL) 60). 

Note: the user can always call breakO himself to obtain combination of options 
breaki not directly available with bfgak and trace . These two functions 
merely provide convenient ways of calling breakO, and will serve for most uses. 

Breakin 

Breakin enables the user to insert a break, i.e. a call to breaki , at a 
specified location in an interpreted function. For example, if foo calls fie , 
inserting a break in foo before the call to fie is similar to breaking fie. 
However, breakin can be used to insert breaks before or after prog labels, 
particular SETQ expressions, or even the evaluation of a variable. This is 
because breakin operates by calling the editor and actually inserting a call to 
breaki at a specified point inside of the function. 

The user specifies where the break is to be inserted by a sequence of editor 
commands. These commands are preceded by BEFORE, AFTER, or AROUND, which 
breakin uses to determine what to do once the editor has found the specified 
point, i.e. put the call to breaki BEFORE that point, AFTER that point, or 
AROUND that point. For example, (BEFORE COND) will insert a break before the 
first occurrence of cond , (AFTER COND 2 1) will insert a break after the 
predicate in the first cond clause, (AFTER BF (SETQ X &)) after the last place 
X is set. Note that (BEFORE TTY:) or (AFTER TTY:) permit the user to type in 
commands to the editor, locate the correct point, and verify it for himself 
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breakin[fn;where;vrhen;coois] breakln is an n lambda , when and corns are similar 

to when and coins for breakO, except that if when 
is HIL, T is used, where specifies where in the 
definition of fjl call to breakl is to be 
inserted. (See earlier discussion). 

If fn is a compiled function, breakin returns 
(fn UNBREAKABLE) as its value. 

If fn is interpreted, breakin types SEARCHING... 
while it calls the editor. If the location 
specified by where is not found, breakin types 
(NOT FOUND) and exits. If it is found, breakin 
adds the property BROKEN-IN with value T, and the 
property BRKINFO with value (where when corns) to 
the property list of fn, and adds fn to the front 
of the list brokenfns . 

Multiple break points, can be inserted with a 
single call to breakin by using a list of the form 
((BEFORE ...) .. (AROUND ...)) for where . It is 
also possible to call break or trace on a function 
which has been modified by breakin, and conversely 
to breakin a function which has been redefined by 
a call to break or trace . 

unbreakCx] unbreak is a nospread n lambda . It takes an 

indefinite number of functions modified by break, 
trace , or breakin and restores them to their 
original state by calling unbreakO . Value is list 
of values of unbreakO. 
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unbreak[] will unbreak all functions on brokenfns, 
in reverse order. It first sets brkinfolst to 

NIL., 

unbreak[T] unbreaks Just the first function on 
brokenfns . i.e., the most recently broken 
function. 

restores fn to its original state. If fn was not 
broken, value is (NOT BROKEN) and no changes are 
made. If fn was modified by breakin , unbreakin is 
called to edit it back to its original state. If 
fn was created from (fnl IN fn2), i.e. if it has a 
property ALIAS, the function in which fn appears 
is restored to its original state. All dummy 
functions that were created by the break are 
eliminated. Adds property value of BRKINFO to 
(front of) brkinfolst . 

Note: unbreakO[(fnl IN fnZ)] is allowed: unbreakO 
will operate on fnl-IN-fnZ instead. 

performs the appropriate editing operations to 
eliminate all changes made by breakin . fn may be 
either the name or definition of a function. 
Value is fn. Unbreakin is automatically called by 
unbreak if fn has property BROKEN-IN with value T 
on its property list. 

is an n lambda , nospread function for rebreaking 
functions that were previously broken without 
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changenameC fn ; from ; to ] 



virginfnCfn;flg] 



having to respecify the break information. For 
each function on x» rebreak searches brktnfolst 
for break(s) and performs the corresponding 
operation. Value is a list of values 
corresponding to calls to breakO or breakin . If 
no information is found for a particular function, 
value is (fn - NO BREAK INFORMATION SAVED). 

rebreakC] rebreaks everything on brkinfolst , i.e., 
rebreak[] is the inverse of unbreakC]. 

rebreakC T] rebreaks Just the first breiak on 
brkinfolst . i.e., the function most recently 
unbroken . 

changes all occurrences of from to to in fn. fn 
may be compiled or blockcompiled. Value is fn if 
from was found, otherwise NIL. Does not perform 
any modifications of property lists. Note that 
from and to do not have to be functions, e.g. they 
can be names of variables, or any other literals. 

is the function that knows how to restore 
functions to their original state regardless of 
any amount of breaks, breakins, advising, 
compiling and saving exprs, etc. It is used by 
prettyprint . define , and the compiler. If 
flgaNIL. as for prettyprint . it does not modify 
the definition of fn in the process of producing a 
"clean" version of the definition, i.e. it works 
on a copy. If flgsT as for the compiler and 
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define , it physically restores the function to its 
original state, and prints the changes it is 
making, e.g. FOO UNBROKEN, FOO UNADVISED, FOO 
NAMES RESTORED, etc. Value is the virgin function 
definition. 

baktraceCposi ;pos2;skipfn;varsf lg;*foriii*flg;allflg] prints backtrace from 

post to pos2 . If skipfn is not NIL, and 
sklpfn[stknan)G[pos]] is T, pos is skipped 
(including all variables). 
varsflg sT for backtrace a la BTV 
varsflflsT, «forin*flg aT - BTV* 
varsflg sT. allflfl=T - BTV! 
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SECTION 16 
ERROR HANDLING 



16.1 Unbound Atoms and Undefined Functions 



Whenever the interpreter encounters an atomic form with no binding on the push- 
down list, and whose value contains the atom NOBIND,^ the interpreter calls 
the function faulteval. Similarly, faulteyal is called when a list is 
encountered, car of which is not the name of a function or a function object. 
The value returned by faulteval is used by the interpreter exactly as though it 
were the value of the form. 



faulteval is defined to print either U. 6. A., for unbound atom, or U.O.F., for 
undefined function, and then to call breakl giving it the offending form as 
brkexp .*^ Once inside the break, the user can set the atom, define the function, 
return a specified value for the form using the RETURN command, etc., or abort 



All atoms are initialized (when they are created by the read program) with 
their value cells (car of the atom) NOBIND, their function cells NIL, and 
their property lists ( cdr of the atom) NIL. 



See Appendix 2 for complete description of INTERLISP interpreter. 



If DWIM is enabled (and a break is going to occur), faulteval also prints 
the offending form (in the case of a U.S.A., the parent form) and the name 
of the function which contains the form. For example, if FOO contains 
(CONS X FIE) and FIE is unbound, faulteval prints: 

U.S.A. FIE [In FOO] In (CONS X FIE). Note that if DWIN is not enabled, the 
user can obtain this information after he is inside the break via the IN? 

command. 
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the break using the t comniand.. If the break is exited with a value, the 
computation will proceed exactly as though no error had occurred. 

The decision over whether or not to induce a break depends on the depth of 
computation, and the amount of time invested in the computation. The actual 
algorithm is described in detail below in the section on breakcheck . Suffice 
it to say that the parameters affecting this decision have been adjusted 
empirically so that trivial type-in errors do not cause breaks, but deep errors 
do. 



16.2 Teletype Initiated Breaks 
Control-H 

Section 15 on the break package described how the user could cause a break when 
a specified function was entered. The user can also indicate his desire to go 
into a break at any time while a program is running by typing control-H. At 
the next point a function is about to be entered, the function interrupt is 
called instead, interrupt types INTERRUPTED BEFORE followed by the function 



A similar procedure is followed whenever apply or apply* are called with an 
undefined function, i.e. one whose fntyp is NIL. In this case, faultapply 
is called giving it the function as its first argument and the list of 
arguments to the function as its second argument. The value returned by 
faultapply is used as the value of apply or apply* . faultapply is defined 
to print U.O.F. and then call breakl giving it 
(APPLY (QUOTE fn) QUOTE args)) as brkexp . Once inside the break, the user 
can define the function, return a specified value, etc. If the break is 
exited with a value, the computation will proceed exactly as though no 
error had occurred, faultapply is also called for undefined function calls 
from compiled code. 



As soon as control-H is typed, INTERLI5P clears and saves the input buffer, 
and then rings the bell, indicating that it is now safe to type ahead to 
the upcoming break. If the break returns a value, i.e., is not aborted via 
t or control-D, the contents of the input buffer before the control-H was 
typed will be restored. 
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name, constructs an appropriate break expression, and then calls breakl » The 
user can then examine the state of the computation, and continue by typing OK, 
GO or EVAL, and/or ret from back to some previous point, exactly as with a user 
break* Control-H breaks are thus always 'safe*. Note that control-H breaks 
are not affected by the depth or time of the computation. However, they only 
occur when a function is called, since it is only at this time that the system 
is in a "clean" enough state to allow the user to interact. Thus, if a 
compiled program is looping without calling any functions, or is in a I/O wait, 
control-H will not affect it. Control-B, however, will. 

Control-B 

Control-B is a stronger interruption than control-H. It effectively generates 

an immediate error. This error is treated like any other error except that it 

ft 

always causes a break, regardless of the depth or time of the computation. 
Thus if the function FOG is looping internally, typing control-B will cause the 
computation to be stopped, the stack unwound to the point at which FOO was 
called, and then cause a break. Note that the internal variables of FOO are 
not available in this break, and similarly, FOO may have already produced some 
changes in the environment before the control-B was typed. Therefore whenever 
possible, it is better to use control-H instead of control-B. 

Control-E 

If the user wishes to Oibort a computation, without causing a break, he should 
type control-E. Control-E does not go through the normal error machinery of 
scanning the stack, calling breakcheck, printing a message, etc. as described 
below, but simply types a carriage-return and unwinds. 



However, setting helpflag to NIL will suppress the break. See discussion 
of breakcheck below. 
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16.3 Other Types of Errors 



In addition to U.B.A. and U.D.f". errors, there are currently 28 other error 
types in INTERLISP, e.g. P-STACK OVERFLOW, NON-NUMERIC ARC. FILE NOT OPEN, 
etc. A complete list is given later in this section. When an error occurs, 
the decision about whether or not to break is handled by breakcheck and is the 
same as with U.B.A. and U.D.F. errors. If a break is to occur, the exact 
action that follows depends on the type of error. For example, if a break is 
to occur following evaluation of (RPLACA NIL (AOOl 5)) (which causes an 
ATTEMPT TO RPLAC NIL error), the message printed will be (RPLACA BROKEN), 
brkexp will be (RPLACA U V W), U will be bound to NIL, V to 6, and W to NIL, 
and the stack will look like the user had broken on rplaca himself. Following 
a NON-NUMERIC ARG error, the system will type IN followed by the name of the 
most recently entered function, and then (BROKEN). The system will then 
effectively be in a break inside of this function, brkexp will be a call to 
ERROR so that if the user types OK or EVAL or GO, a ? will be printed and the 
break maintained. However, if the break is exited with a value via the RETURN 

7 

command, the computation will proceed exactly as though no error had occurred. 

16.4 Breakcheck - When to Break 

The decision as to whether or not to induce a break when an error occurs is 
handled by the function breakcheck . The user can suppress all error breaks by 
setting the variable helpflag to NIL (initially set to T). If helpf lag aT. the 
decision is affected by two factors: the length of time spent in the 



Presumably the value will be a number, or the error will occur again. 

Breakcheck is not actually available to the user for advising or breaking 
since the error package is block-compiled. 
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computation, and the depth of the computation at the time of the error. If the 
time is greater than helptlme or the depth is greater than helpdepth , 
breakcheck returns T, meaning a break will occur. 

Since a function is not actually entered until its arguments are evaluated, '^^ 
the depth of a computation is defined to be the sum of the number of function 
calls plus the number of internal calls to eval . Thus if the user types in the 
expression [MAPC FOO (FUNCTION (LAMBDA (X) (COND ((NOT (MEMB X FIE)) (PRINT X] 
for evaluation, and FIE is not bounds at the point of the U.S.A. FIE error, two 
functions, mapc and cond, have been entered, and there are three internal calls 
to eval corresponding to the evaluation of the forms 
(COND ((NOT (MEHB X FIE)) (PRINT X))), (NOT (MEMB X FIE)), and (MEMB X FIE).^^ 
The depth is thus 5. 

breakcheck begins by searching back up the parameter stack looking for an 

IP 

errorset .*^ At the same time, it counts the number of internal calls to eval . 
as indicated by pseudo-variable bindings called eval-blips . See Section 12. 
As soon as (if) the number of eval-blips exceeds helpdepth , breakcheck can stop 
searching for errorset and return T, since the position of the errorset is only 
needed when a break is not going to occur. Otherwise, breakcheck continues 



9 
10 

11 
12 



Except that control-B errors always break. 

Unless of course the function does not have its arguments evaluated, i.e. 
is an FEXPR, FEXPR*, CFEXPR, CFEXPR*, FSUBR or FSUBR*. 

For complete discussion of the stack and the interpreter, see Section 12. 

errorsets are simply markers on the stack indicating how far back unwinding 
is to take place when an error occurs, i.e. they segment the stack into 
sections such as that if an error occurs in any section, control returns to 
the point at which the last errorset was entered, from which NIL is 
returned as the value of the errorset. See page 16.14. 
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searching until either an errorset is found or the top of the stack is 
reached. Brcakcheck then completes the depth check by counting the number of 
function calls between the error and the last errorset , or the top of the 
stack. If the number of calls plus the number of eval-blips (already counted) 
is greater than or equal to helpdepth , initially set to 9,^^ breakcheck returns 
T. Otherwise, it records the position of the last errorset , and the value of 
errorset 's second argument, which is used in deciding whether to print the 
error message, and returns NIL. 

breakcheck next measures the length of time spent in the computation by 
subtracting the value of the variable helpclock from the value of (CLOCK 2), 
If the difference is greater than helptime milliseconds, initially set to 1000, 
then a break will occur, i.e., breakcheck returns T, otherwise NIL. The 
variable helpclock is rebound to the current value of (CLOCK 2} for each 
computation typed in to lispx or to a break. 

The time criterion for breaking can be suppressed by setting helptime to NIL 
(or a very big number), or by binding helpclock to NIL. Note that setting 
helpclock to NIL will not have any effect because helpclock is rebound by lispx 
and by break . 

If breakcheck is NIL, i.e., a break is not going to occur, then if an errorset 
was found, NIL is returned (via retfrom ) as the value of the errorset . after 
first printing the error message if the errorset 's second argument was TRUEw 
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If the second argument to the errorset is INTERNAL, the errorset is ignored 
and searching continues. See discussion of errorset, page 16.14. 

14 

Arrived at empirically, takes into account the ovek'head due to lispx or 
break . 

Whose value is number of milliseconds of compute time. See Section 21. 
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If there was no errorset , the message is printed, and control returns to 
evalgt . This procedure is followed for all types of errors. 

Note that for all error breaks for which a break occurs, breakl will clear and 
save the input buffer. If the break returns a value, i.e., is not aborted via 
t or control-D, the input buffer will be restored as described in Section 15. 

16.5 Error Types 

There are currently twenty-eight error types in the INTERLISP system. They are 
listed below by error number. The error is set internally by the code that 
detects the error before It calls the error handling functions. It is also the 
value returned by errorn if called subsequent to that type of error, and is 
used by errormess for printing the error message. 

Most error types will print the offending expression following the message, 
e.g., NON-NUMERIC ARG NIL is very common. Error type 18 (control-B) always 
causes a break (unless helpflag is NIL). All other errors cause breaks if 
breakcheck returns T. 

0 NONXMEN reference to non-existent memory. Usually 

indicates system is very sick. 

1 Currently not used. 

2 P-STACK OVERFLOW occurs when computation is too deep, either with 

respect to number of function calls, or number of 
variable bindings. Usually because of a non- 
terminating recursive computation, i.e. a bug. 
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3 ILLEGAL RETURN 

4 ILLEGAL ARG - PUTO 

5 ARG NOT ATOM - SET 

6 ATTEMPT TO SET NIL 

7 ATTEMPT TO RPLAC NIL 

8 UNDEFINED OR ILLEGAL GO 

9 FILE WON'T OPEN 

10 NON-NUMERIC ARG 

11 ATOM TOO LONG 

12 ATOM HASH TABLE FULL 

13 FILE NOT OPEN 

14 ARG NOT ATOM 

15 TOO MANY FILES OPEN 



call to return when not inside of an interpreted 
prog . 

second argument to putd (the definition) is not 
NIL, a list, or a pointer to compiled code. 

first argument to set, setq , or setqq (name of the 
variable) is not a literal atom. 

via set or setq 

attempt either to rplaca or to rplacd NIL with 
something other than NIL. 

go when not inside of a prog , or go to nonexistent 
label . 

From infile or outfile. Section 14. 

a numeric function e.g. iplus , itimes . igreaterp , 
expected a number. 

> 100 characters. 

no room for any more (new) atoms. 

from an I/O function, e.g. read , print , closef . 



> 16 including teletype. 
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16 END OF FILE 



from an input function, e.g. read , readc . ratom . 
Note: the file will then be closed. 



17 ERROR call to error . 

18 BREAK control-B was typed. 

19 ILLEGAL STACK ARC a stack function expected a stack position and was 

given something else. This might occur if the 
arguments to a stack function are reversed. Also 
occurs if user specified a stack position with a 
function name, and that function was not found on 
the stack. See Section 12. 



20 FAULT IN EVAL artifact of bootstrap. Never occurs after 

faulteval has been defined as described earlier. . 

21 ARRAYS FULL system will first initiate a GC: 1, and if no 

array space is reclaimed, will then generate this 
error. 

22 DIRECTORY FULL no new files can be created until user deletes 

some old ones and expunges. 

23 FILE NOT FOUND file name does not correspond to a file in the 

corresponding directory. Can also occur if file 
name is ambiguous. 

24 FILE INCOMPATIBLE - SYSIN from sysin . Section 14. 

25 UNUSUAL CDR ARG LIST a form ends in a non-list other than NIL, e.g. 

(CONS T . 3). 
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26 HASH TABLE FULL 



see hash link functions, Section 7. 



27 ILLEGAL ARG Catch-all error. Currently used by evala , arg , 

funarg , allocate , rplstring . and sfptr . 

28 ARG NOT ARRAY elt or seta given an argument that is not a 

pointer to the beginning of an array. 

29 ILLEGAL OR IMPOSSIBLE BLOCK 

From getblk or relblk . See Section 21. 

30 currently not used. 

31 LISTS FULL following a GC: 8, if a sufficient amount of list 

words have not been collected, and there is no un- 
allocated space left in the system, this error is 
generated. 

Many system functions, e.g. define , arglist , advise , log , expt , etc, also 
generate errors with appropriate messages by calling error (see page 16.12) 
which causes an error of type 16. 

Error handling by error type 

Occasionally the user may want to treat certain error types different than 
others, e.g. always break, never break, or perhaps take some corrective action. 
This can be accomplished via errortypelst . errortypelst is a list of elements 
of the form (n expression), where n is one of the 28 error numbers. After 
breakcheck has been completed, but before any other action is taken, 
errortypelst is searched for an element with the same error number as that 
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causing the error. If one is found, and the evaluation of the corresponding 
expression produces a non-NIL value, the value is substituted for the offender, 
and the function causing the error is reeentered. 



For this application, the following three variables may be useful: 



errormess 



car is the error number, cadr the "offender" e.g. 
(10 NIL) corresponds to NON-NUNERIC AR6 NIL error. 



errorpos 



position of the function in which the error 
occurred, e.g. stknaineC errorpos] might be IPLUS, 
RPLACA, INFILE, etc. 



breakchk 



value of breakcheck , i.e. T means a break will 
occur, NIL means one will not. 



For example, putting 

CIO (AND (NULL (CADR ERRORMESS)) 

(SELECTQ (STKNAME ERRORPOS) 

((IPLUS ADOl SUBl) 0) 
(ITIMES 1) 

(PROGN (SETQ BREAKCHK T) NIL] 

errortypelst would specify that whenever a NON-NUMERIC AR6 - NIL error 
occurred, and the function in question was IPLUS, AODl, or SUBl, 0 should be 
used for the NIL. If the function was ITIMES, 1 should be used. Otherwise, 
always break. Note that the latter case is achieved not by the value returned, 
but by the effect of the evaluation, i.e. setting BREAKCHK to T. Similarly, 
(16 (SETQ BREAKCHK NIL)) would prevent END OF FILE errors from ever breaking. 
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16.6 Error Functions 



errorxCerxni] is the entry to the error routines. If erxm sNIL, 

errorn[] is used to determine the error-message. 
Otherwise, seterrorn[erxm] is perfortnied* 'setting' 
the error type and argument. Thus following 
either errorx[(10 T)] or (PLUS T), errornC ] is 
(10 T). errorx calls breakchedk, and either 
induces a break or prints the message and unwinds 
to the last errorset . Note that errorx can be 
called by any program to intentionally induce an 
error of any type. However, for most 
applications, the function error will be more 
useful. 

error[messl ;mess2;nobreak] The message that is (will be) printed is messi 

(using prinl ), followed by a space if messi is an 

atom, otherwise a carriage return » Then mess2 is 

printed, using prinl if mess2 is a string, 

otherwise print . e.g., errorC "NON-NUMERIC AR6'';T] 

will print 

NON-NUMERIC ARG 
T 

and error[FOOf''NOT A FUNCTION"] will print 
FOO NOT A FUNCTION. (If both messl and mess2 are 
NIL, the message is simply ERROR.) 

If nobrealcsT, error prints its message and then 
calls error! . Otherwise it calls 

errorxC(17 (messl . mess2))], i.e. generates an 
error of type 17, in which case the decision as to 
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whether or not to break, and whether or not to 
print a message , is handled as per any other 
error. 



helpCnessl ;iiiess2] 



prints inessl and mess2 a la error , and then calls 
break 1 . If both messl and mess2 are NIL, HELPf is 
used for the message, help is a convenient way to 
program a default condition, or to terminate some 
protion of a program which theoretically the 
computation is never supposed to reach. 



error ![ ] 
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programmable control-E, i.e., immediately returns 
from last errorset or resets. 



resetC ] 



Programmable control-D, i.e. immediately returns 
to the top level. 



errornC ] 



returns information about the last error in the 
form (n x) where n is the error type number and x 
is the expression which was (would have been) 
printed out after the error message . Thus 
following (PLUS T), errorn[] is (10 T). 



errorraess[u] 



prints message corresponding to an errorn that 
yielded u. For example, errormess[ ( 10 T)] would 
print 

NON-NUMERIC ARC 
T 



Pronounced "error-bang' 
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errorsetCu;v] 
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performs eval[u]. Note that errorset is a lejnbda- 



type of function, and that its arguments are 
evaluated before it is entered, i.e. errorset[x] 
means eval is called with the value of x* In roost 
cases, ersetq and nlsetq (described below) are 
more useful. If no error occurs in the evaluation 
of u, the value of errorset is a list containing 
one element, the value of evalCu]. If an error 
did occur, the value of errorset is NIL. 

The argument v controls the printing of error 
messages if an error occurs, if v"T, the error 
message is printed; if vsNIL it is not. 

If vsINTERNAL, the errorset is ignored for the 
purpose of deciding whether or not to break or 
print a message. However, the errorset is in 
effect for the purpose of flow of control, i.e. if 
an error occurs, this errorset returns NIL. 



ersetq[ersetx] 



n lambda , performs 



errorse tC erse tx ; t ] , 



i.e. 



(ERSETQ (FOO)) 



is 



equivalent 



to 



(ERRORSET (QUOTE (FOO)) T). 



nlsetq[nlsetx3 



n lambda , performs errorset[nlsetx;NIL]. 



17 



errorset is a subr , so the names "u" and "v" don't actually appear on the 
stack nor will they affect the evaluation. 
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SECTION 17 

AUTOMATIC ERROR CORRECTION - THE DWIN FACILITY 



17.1 Introduction 

A surprisingly large percentage of the errors made by INTERLISP users are of 
the type that could be corrected by another LISP progranmer without any 
information about the purpose of the program or expression in question, e.g. 
misspellings, certain kinds of parentheses errors, etc. To correct these types 
of errors we have implemented in INTERLISP a DWIN facility, short for DO-What- 
I-Nean. DWIN is called automatically whenever an error occurs in the 
evaluation of an INTERLISP expression. DWIN then proceeds to try to correct 
the mistake using the current context of computation plus information about 
what the user had previously been doing, (and what mistakes he had been making) 
as guides to the remedy of the error. If DWIN is able to make the correction, 
the computation continues as though no error had occurred. Otherwise, the 
procedure is the same as though DWIN had not intervened: a break occurs, or an 
unwind to the last errorset, as described in Section 16. The following 
protocol illustrates the operation of DWIN. 



DWIN was designed and implemented by W. Teitelman.' It is discussed in 
[TeiZ]. 

Currently, DWIN only operates on unbound atoms and undefined function 
errors. 
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Example 



The user defines a function fact of one argument, n. The value of fact[n] is 
to be n factorial. 



*-DEFINEO((FACT (LAMBDA (N) (COND 

((ZEROP N9 1) ((T (ITIMES N (FACT 8SUB1 N] 

(FACT) 



Note that the definition of fact contains several mistakes! I times and fact 
have been misspelled; the 9 in N9 was Intended to be a right parenthesis, but 
the shift key was not depressed; similarly, the 8 in 8SUB1 was intended to be a 
left parenthesis; and finally, there is an extra left parenthesis in front of 
the T that begins the final clause in the conditional. 



-PRETTYPRINT((FACCT] [1] 
=PRETTYPRINT [2] 
=FACT [3] 

(FACT 

[LAMBDA (N) 
(CONO 

((ZEROP N9 1) 

((T (ITIM3 N (FACCT 8SUB1 N]) 

(FACT) 



After defining fact, the user wishes to look at its definition using 
PRETTYPRINT, which he unfortunately misspells. [1] Since there is no function 
PRETTYPRINT in the system, a U.D.F. error occurs, and OWIN is called. DWIN 
invokes its spelling corrector, which searches a list of functions frequently 
used (by this user) for the best possible match. Finding one that is extremely 
close, DWIN proceeds on the assumption that PRETTYPRINT meant PRETTYPRINT, 
notifies the user of this, [2] and calls prettyprint . 

At this point, PRETTYPRINT would normally print (FACCT NOT PRINTABLE) and exit, 
since facet has no definition. Note that this is not an INTERLISP error 
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condition, so that DWIN would not be called as described above. However, it is 
obviously not what the user meant. 

This sort of mistake is corrected by having prettyprint itself explicitly 
invoke the spelling corrector portion of OWIN whenever given a function with no 
expr definition. Thus with the aid of OWIH, prettyprint is able to determine 
that the user wants to see the definition of the function fact »C3] and proceeds 
accordingly. 



«-FACT(3] [4] 

N9 [IN FACT] -> N ) ? YES 

[IN FACT] (COND — ((T —))) -> 

(COND — (T — )) 

ITIMS [IN FACT] -> ITIHES [5] 

FACCT [IN FACT] -> FACT 

8SUBI [IN FACT] -> ( SUB! 7 YES 
6 

♦•PP FACT [6] 

(FACT 

[LAMBDA (N) 
(COND 

((ZEROP N) 
1) 

(T (ITHES N (FACT (SUBl N]) 

FACT 



The user now calls his function fact . [4] During its execution, five errors 
occur, and DWIN Is called five times. [5] At each point, the error is corrected, 
a message printed describing the action taken, and the computation allowed to 
continue as if no error had occurred. Following the last correction, 6 is 
printed, the value of fact(3). Finally, the user prettyprints the new, now 
correct, definition of fact. [6] 

In this particular example, the user was shown operating in TRUSTING mode, 
which gives DWIN carte blanche for most corrections. The user can also operate 
in CAUTIOUS mode, in which case DWIN will inform him of intended corrections 
before they are made, and allow the user to approve or disapprove of then. For 
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most corrections, if the user does not respond in a specified interval of time, 
DWIN automatically proceeds with the correction, so that the user need 
intervene only when he does not approve. Sample output is given below. Note 
that the user responded to the first, second, and fifth questions; DWIN 
responded for him on the third and fourth. 



We have put a great deal of effort into making DWIN 'smart', and experience 
with perhaps fifty different users indicates we have been very successful; DWIN 
seldom fails to correct an error the user feels it should have, and almost 
never mistakenly corrects an error. However, it is important to note that even 
when DWIN is wrong, no harm is done: since an error had occurred, the user 
would have had to intervene anyway if DWIN took no action. Thus, if DWIN 
mistakenly corrects an error, the user simply interrupts or aborts the 
computation, UNDOes the DWIN change using UNDO described in Section 22, and 
makes the correction he would have had to make without DWIN. It is this benign 
quality of DWIN that makes it a valuable part of INTERLISP. 



Except perhaps if DWIN's correction mistakenly caused a destructive 
computation to be initiated, and information was lost before the user eould 
Interrupt. We have not yet had such an incident occur. 



♦-FACTO) 

N9 [IN FACT] -> N ) ? YES 
U.D.F. T [IN FACT] FIX? YES 
[IN FACT] (COND ((T — ))) -> 
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[2] 



(COND -- (T ")) 



ITIMS [IN FACT] -> ITINES ? ...YES 
FACCT [IN FACT] -> FACT ? ...YES 
8SUB1 [IN FACT] -> ( SUBl 7 NO 
U.B.A. 

(8SUB1 BROKEN) 



[3] 
[4] 
[5] 
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17.2 Interaction with DWIH 



DWm is enabled by performing either DWINtC], for CAUTIOUS mode, or DWINCT] for 
TRUSTING mode."^ In addition to setting dwimflg to T and redefining faulteval 
faultapply as described on page 17.14» DWIM[C] sets approvef Ig to T, while 
DWIM[T] sets approvef Ifl to NIL. The setting of approveflg determines whether 
or not the user wishes to be asked for approval before a correction that will 
modify the definition of one of his functions. In CAUTIOUS mode, i.e. 
approveflg sTt DWIN will asK for approval; in TRUSTING mode, DWIN will not. For 
corrections to expressions typed in by the user for immediate execution,^ DWIN 
always acts as though approveflg were NIL, i.e. no approval necessary. In 
either case, DWIN always informs the user of its action as described below. 



Spelling Correction Protocol 

The protocol used by DWIN for spelling corrections is as follows: If the 
correction occurs in type-in, print s followed by the correct spelling, 
followed by a carriage-return, and then continue, e.g. 



INTERLISP arrives with DWIN enabled in CAUTIOUS mode. DWIN can be disabled 
by executing DWIN[ ] or by setting dwimflg to NIL. See page 17.23. 

Typed into lispx . lispx is used by evalqt and break , as well as for 
processing the editor's E command. Functions that call the spelling 
corrector directly, such as editdefault (Section 9), specify whether or not 
the correction is to be handled as type-in. For example, in the case of 
editdefault . commands typed directly to the editor are treated as type-in, 
so that corrections to them will never require approval. Commands given as 
an argument to the editor, or resulting from macro expansions, or from IF, 
LP, ORR commands etc. are not treated as type-in, and thus approval will be 
requested if approveflg sT. 



6 



For certain types of corrections, e.g. run-on spelling corrections, 8-9 
errors, etc., dwim always asks for approval, regardless of the setting of 

approveflg . 
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user types: -(SETQ FOO (NCOCN FIE FUH)) 
DWIN types: -NCONC 



If the correction does not occur in type-in » print the incorrect spelling* 
followed by [IN funct ion-name L ->. and then the correct spelling* e.g. 
ITIMS [IN FACT] -> ITIHES as shown on page 17.3.^ Then, if approvef Ig sNIL, 
print a carriage return* make the correction and continue. Otherwise* print a 
few spaces and a 7 and then wait for approval.^ The user then has six options. 
He can: 

1. Type Y; DWIN types ES* and proceeds with the correction. 

2. Type N; DWIN types 0* and does not make the correction. 

3. Type t; DWIN does not make the correction* and furthermore guarantees 
that the error will not cause a break. See footnote on page 17.15. 

4. Type control-E; for error correction* this has the same effect as 
typing N. 

p 

5. Do nothing; in which case DWIN will wait a specified interval, and if 
the user has not responded, DWIN will type ... followed by the default 
answer.' 

6. Type space or carriage-return; in which case DWIN will wait 
indefinitely. This option is intended for those cases where the user 
wants to think about his answer, and wants to insure that DWIN does 
not get 'impatient' and answer for him. 
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The appearance of -> is to call attention to the fact that the user's 
function will be or has been changed. 

Whenever an interaction is about to take place and the user has typed 
ahead, DWIN types several bells to warn the user to stop typing, then 
clears and saves the input buffers, restoring them after the interaction is 
complete. Thus if the user has typed ahead before a DWIN interaction* DWIN 
will not confuse his type ahead with the answer to its question, nor will 
his type ahead be lost. 

Equal to dwimwalt seconds. DWIN operates by dismissing for 500 
milliseconds, then checking to see if anything has been typed. If not, it 
dismisses again, etc. until dwlmwait seconds have elapsed. Thus, there 
will be a delay of at most 1/2 second before DWIN responds to the user's 
answer. 

The default is always YES unless otherwise stated. 
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The procedure for spelling correction on other than INTERLISP errors is 
analogous. If the correction is being handled as type-in, DWIN 
prints B followed by the correct spelling, and returns it to the function that 
called DWIN, e.g. bPacT as shown on page 17.2. Otherwise, DWIN prints the 
incorrect spelling, followed by the correct spelling. Then if approvef lg «NIL, 
DWIN prints a carriage^return and returns the correct spelling. Otherwise, 
DWIN prints a few spaces and a 7 and then waits for approval. The user can 
then respond with Y, N, control-E, space, carriage return, or do nothing as 
described. 

Note that since the spelling corrector itself is not errorset protected, typing 
N and typing control-E may have different effects when the spelling corrector 
is called directly.-*' The former simply instructs the spelling corrector to 
return NIL, and lets the calling function decide what to do next^ the latter 
causes an error which unwinds to the last errorset, however far back that may 
be. 

Parentheses Errors Protocol 

As illustrated earlier on page 17.3, DWIN will correct errors consisting of 
typing 8 for left parenthesis and 9 for right parenthesis. In these cases, the 
interaction with the user is similar to that for spelling correction. If the 
error occurs in type- in, DWIN types « followed by the correction, e.g. 



Otherwise, DWIN prints the offending atom, [IN function -name], the proposed 



The DWIN error correction routines are errorset protection. 



user types: 
DWIN types: 
lispx types: 



«-(SETQ FOO SCONS FIE FUN] 
= ( CONS 
(A B C 0) 
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correction, a few spaces and a 7* and then waits for approval, e.g. 
N9 [IN FACT] -> N ) ? as shown on page 17.3. The user then has the same six 
options as for spelling correction.'^ If the user types Y, DWIN then operates 
exactly the same as when approveflg sNIL, i.e. makes the correction and prints 
its message. 

U.D.F. T Errors Protocol 

DWIN corrects certain types of parentheses errors involving a T clause in a 
conditional, namely errors of the form: 

1. (CONO --) (T --), i.e. the T clause appears outside and immediately 
following the COND; 

2. (COND (-- & (T --))>, i.e. the T clause appears inside a previous 
clause; and 

3. (COND ((T -•>))), i.e. the T clause has an extra pair of parentheses 
around itJ^ 

If the error occurs in type-in, DWIN simply types T FIXED and makes the 
correction. Otherwise if approveflg sNIL, DWIN makes the correction, and prints 
a message consisting of [IN function-name], followed by one of the above 
incorrect forms of COND, followed by then on the next line the 

corresponding correct form of the COND, e.g. 



except the waiting time is 3* dwimwait seconds. 

For U.D.F. T errors that are not one of these three types, DWIN takes no 
corrective action at all, i.e. the error will occur. 
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[IN FACT] (CONO 
(COND 



- ((T -))) -> 

- (T -)) 



as shovm on page 17.3. 

If approver Ig sT, DWIM prints U.O.F. T, followed by [IN function-nane], several 
spaces, and then FIX? and waits for approval. The user then has the same 
options as for spelling corrections and parenthesis errors. If the user types 
Y or defaults, DWIN then proceeds exactly the same as when approveflg «NIL, i.e. 
nakes the correction and prints its message, as shown on page 17.4. 

Having made the correction, DWIN must then decide how to proceed with the 
computation. In case 1, (COND — ) (T --), DWIN cannot know whether the last 
clause of the COND before the T clause succeeded or not, i.e. if the T clause 
had been inside of the COND, would it have been entered? Therefore DWIN asks 
the user 'CONTINUE WITH T CLAUSE' (with a default of YES). If the user types 
N, DWIN continues with the form after the CONO, i.e. the form that originally 
followed the T clause. 

In case 2, (COND (-- & (T --))), DWIN has a different problem. After moving 
the T clause to its proper place, DWIN must return as the value of the COND, 
the value of the expression corresponding to &. Since this value is no longer 
around, DWIN asks the user, 'OK TO REEVALUATE' and then prints the expression 
corresponding to &. If the user types Y, or defaults, DWIN continues by 
reevaluating &, otherwise DWIN aborts, and a U.O.F. T error will then occur 
(even though the COND has in fact been fixed).^^ 



If DWIN can determine for itself that the form can safely be reevaluated, 
it does not consult the user before reevaluating. DWIN can do this if the 
form is atomic, or car of the form is a member of the list okreevalst , and 
each of the arguments can safely be reevaluated, e.g. 
(SETQ X (CONS (IPLUS Y Z) W)) is safe to reevaluate because SETQ, CONS, and 
IPLUS are all on okreevalst. 
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In case 3, (COND ((T —))), there is no problem with continuation, so no 
further interaction is necessary. 

17.3 Spelling Correction 

The spelling corrector is given as arguments a misspelled word (word means 
literal atom), a spelling list (a list of words), and a number: xword . splst , 
and rel respectively. Its task is to find that word on splst which is closest 
to xword , in the sense described below. This word is called a respelling of 
xword . rel specifies the minimum 'closeness* between xword and a respelling. 
If the spelling corrector cannot find a word on splst closer to xword than rel , 
or if it finds two or more words equally close, its value is NIL, otherwise its 
value is the respelling. 

The exact algorithm for computing the spelling metric is described later on 
page 17.20, but briefly 'closeness* is inversely proportional to the number of 
disagreements between the two words, and directly proportional to the length of 
the longer word, e.g. PRTTYPRNT is 'closer* to PRETTYPRINT than CS is to CONS 
even though both pairs of words have the same number of disagreements. The 
spelling corrector operates by proceeding down splst , and computing the 
closeness between each word and xword , and keeping a list of those that are 
closest. Certain differences b(3tween words are not counted as disagreements, 
for example a single transposition, e.g. CONS to CNOS, or a doubled letter, 
e.g. CONS to CONSS, etc. In the event that the spelling corrector finds a word 
on splst with no disagreements, it will stop searching and return this word as 
the respelling. Otherwise, the spelling corrector continues through the entire 



The spelling corrector can also be given an optional functional argument, 
fn , to be used for selecting out a subset of splst , i.e. only those members 
of splst that satisfy fn will be considered as possible respellings. 
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spelling list. Then if it has found one and only one 'closest* word, it 
returns this word as the respelling. For example, if xword is VONS, the 
spelling corrector will probably return CONS as the respelling. However, if 
xword is CONZ, the spelling corrector will not be able to return a respelling, 
since CONZ is equally close to both CONS and CONO. If the spelling corrector 
finds an acceptable respelling, it interacts with the user as described 
earlier. 

In the special case that the misspelled word contains one or more alt-modes, 
the spelling corrector operates somewhat differently. Instead of trying to 
find the closest word as above, the spelling corrector searches for those words 
splst that match xword , where an alt-mode can match any number of characters 
(including 0), e.g. F00$ matches FOOl and FOO, but not NEWFOO. SFOOS matches 
all three. In this case, the entire spelling list is always searched, and if 
more than one respelling is found, the spelling corrector prints AMBIGUOUS, and 
returns NIL. For example, CON$ would be ambiguous if both CONS and CONO were 
on the spelling list. If the spelling corrector finds one and only one 
respelling, it interacts with the user as described earlier. 

For both spelling correction and spelling completion, regardless of whether or 
not the user approves of the spelling corrector's choice, the respelling is 
moved to the front of splst . Since many respellings are of the type with no 
disagreements, this procedure has the effect of considerably reducing the time 
required to correct the spelling of frequently misspelled words. 

Spelling Lists 

Although any list of atoms can be used as a spelling list, e.g. editcomsa , 
brokenfns . filelst . etc., four lists are maintained especially for spelling 
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correction: spellingsl , spellinas2 , spellings3 , and userwords . 



Spellingsl is a list of functions used for spelling correction whdn an input is 

typed in apply format, and the function is undefined, e.g/ EDTIF(FOO). 

Spelling sl is initialized to contain defineq , break , makefile , editf , tcompl , 

load , etc . Whenever lispx is given an input in apply format* i.e. a function 

and arguments, the name of the function is added to spellingsl . For example, 

typing CALLS(EOITF) will cause CALLS to be added to spellingsl . Thus if the 

user typed CALLS(EOITF) and later typed CALLLS(EOITV) , since spellingsl would 

IS 

then contain CALLS, DWIN would be successful in correcting CALLLS to CALLS.'" 

SpellingsZ is a list of functions used for spelling correction for all other 
undefined functions. It is initialized to contain functions such as add! , 
append, cond, cons , go, list, n oonc , print , prog , return, setq , etc. Whenever 
lispx is given a non-atomic form, the name of the function is added to 
spellingsZ . For example, typing (RETFROM (STKPOS (QUOTE FOO) 2)) to a break 
would add ret from to spellingsZ . Function names are also added to spellingsZ 
by define, def ineq , load (when loading compiled code), unsavedef . editf , and 
prettyprlnt . 

Spellings3 is a list of words used for spelling correction on all unbound 
atoms. SpellingsS is initialized to edltmacros , breakmacros , brokenfns , and 
advisedfns . Whenever lispx is given an atom to evaluate, the name of the atom 



All of the remarks on maintaining spelling lists apply only when DWIN is 
enabled, as indicated by dwimflg »T. 

Only if the function has a definition. 

If CALLLS(EDITV) were typed before CALLS had been 'seen' and added to 
spellingsl , the correction would not succeed. However, the alternative to 
using spelling lists is to search the entire oblist, a procedure that would 
make spelling correction intolerably slow. 
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is added to spellings3 . *^ Atoms are also added to spelllngs3 whenever they are 
edited by editv , and whenever they are set via rpaq or rpaqq . For example, 
when a file is loaded, all of the variables set in the file are added to 
spellings3 . Atoms are also added to spellinasB when they are set by a lispx 
input, e.g. typing (SETQ FOO (REVERSE (SETQ FIE — ))) will add both FOO and FIE 
to spellingsS . 

Userwords is a list containing both functions and variables that the user has 
referred to e.g. by breaking or editing. Userwords is used for spelling 
correction by arglist , unsavedef , prettyprint , break , editf , advise , etc. 
Userwords is initially NIL. Function names are added to it by define , def ineq . 
load , (when loading compiled code, or loading exprs to property lists) 
unsavedef, editf , edity, editp , prettyprint , etc. Variable names are added to 
userwords at the same time as they are added to spellingsB . In addition, the 
variable lastword is always set to the last word added to userwords , i.e. the 
last function or Variable referred to by the user, and the respelling of NIL Is 
defined to be the value of lastword . Thus, if the user has Just defined a 
function, he can then edit it by simply typing EOITF(), or prettyprint it by 
typing PP( ) . 

Each of the above four spelling lists are divided into two sections separated 
by a NIL. The first section contains the 'permanent' words; the second section 
contains the temporary words. New words are added to the corresponding 
spelling list at the front of its temporary section.*'' (If the word is already 
in the temporary section, it is moved to the front of that section; if the word 
is in the permanent section, no action is taken.) If the length of the 



Only if the atom has a value other than NOBINO. 

Except that functions added to spellingst or spellingsZ by lispx are always 
added to the end of the permanent section. 
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temporary section then exceeds a specified number, the last (oldest) word in 
the temporary section is forgotten, i.e. deleted. This procedure prevents the 
spelling lists from becoming cluttered with unimportant words that are no 
longer being used, and thereby slowing down spelling correction time. Since 
the spelling corrector moves each word selected as a respelling to the front of 
its spelling list, the word is thereby moved into the permanent section. Thus 
once a word is mispelled and corrected. It is considered important and will 
never be forgotten. 

The maximum length of the temporary section for spelllngsi , spellings2 , 
spellings3 and userwords is given by the value of Ispellingsl , #spellings2 , 
#spcllings3 , and #userwords , initialized to 30, 30, 30, and 60 respectively. 
Using these values, the average length of time to search a spelling list for 
one word is about 4 milliseconds.'^' 



17.4 Error Correction 

As described in Section 16, whenever the interpreter encounters an atomic form 
with no binding, or a non-atomic form car of which is not a function or 
function object, it calls the function faulteval . Similarly, when apply is 
given an undefined function, it calls faultapply . When OWIN is enabled, 
faulteval and faultapply are redefined to first call dwlmblocR, a part of the 
DWIN package. If the user aborts by typing control-E^ or if he indicates 
disapproval of DWIN's intended correction by answering N as described on page 



If the word is at the front of the spelling list, the time required is only 
1 millisecond. If the word is not on the spelling list, i.e. the entire 
list must be searched, the time is proportional to the length of the list; 
to search a spelling list of length 60 takes about 7 milliseconds. 
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17.6, or if DWIN cannot decide how to fix the error, dwimblocic returns HIL, 
In this case, faulteval and faultapply proceed exactly as described in Section 
16, by printing a U.B.A. or U.O.f . message, and going into a break if the 
requirements of breakcheck are met, otherwise unwinding to the last errorset . 

If DWIN can (and is allowed to) correct the error, dwimblock exits by 
performing reteval of the corrected form, as of the position of the call to 
faulteval or faultapply . Thus in the example at the beginning of the chapter, 
when DWIM determined that ITIMS was ITIMES misspelled. DWIM called reteval with 
(ITINES N (FACCT 8SUB1 N)). Since the interpreter uses the value returned by 
faulteval exactly as though it were the value of the erroneous form, the 
computation will thus proceed exactly as though no error had occurred. 

In addition to continuing the computation, DWIN also repairs the cause of the 
error whenever possible. Thus in the above example, DWIN also changed (with 
rplaca ) the expression (ITIMS N (FACCT 8SUB1 N)) that caused the error. 

Error correction in DWIN is divided into three categories: unbound atoms, 
undefined cars of form, and undefined function in apply . Assuming that the 
user approves if he is asked, the action taken by DWIN for the various types of 
errors in each of these categories is summarized below. The protocol of DWIH's 
interaction with the user has been described earlier. 
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If the user answers with t, (see page 17.6) dwimblock is exited by 
performing retevalCFAULTEVAL; (ERROR! )], i.e. an error is generated at the 
position of the call to faulteval . 

If the user's program had computed the form and called eval, e.g. performed 
(EVAL (LIST X Y)) and the value of x was a misspelled function; it would 
not be possible to repair the cause of the error, although DWIN could 
correct the misspelling each time it occurred. 
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Unbound Atoms 



1. If the first character of the unbound atom is DWIN assumes that the user 
(intentionally) typed 'atom for (QUOTE atom) and makes the appropriate 
change. No message is typed, and no approval requested. 

If the unbound atom is Just ' itself, DWIN assumes the user wants the next 
expression quoted, e.g. (CONS X '(A B C)) will be changed to 
(CONS X (QUOTE (A B C))). Again no message will be printed or approval 
asked. (If no expression follows the DWIM gives up.) 

2. If CLISP (Section 23) is enabled, and the atom is part of a CLISP 
construct, the CLISP transformation is performed and the result returned, 
e.g. N-1 is transformed to (SUB! N). 

3. If the atom contains an 8, DWIN assumes the 6 was intended to be a left 
parenthesis, and calls the editor to make appropriate repairs on the 
expression containing the atom. DWIN assumes that the user did not notice 
the mistake, i.e. that the entire expression was affected by the missing 
left parenthesis. For example, if the user types 

(SETQ X (LIST (CONS SCAR Y) (CDR Z)) Y), the expression will be changed to 
(SETQ X (LIST (CONS (CAR Y) (CDR Z)) Y)). 

The 8 does not have to be the first character of the atom, e.g. DWIN will 

handle (CONS X8CAR Y) correctly. 

4. If the atom contains a 9, DWIN assumes the 9 was intended to be a right 
parenthesis and operates as in number 3. 

5. If the atom begins with a 7, the 7 is treated as a e.g. 7F00 becomes 
•FOO, and then (QUOTE FOO). 

6. If the atom is an edit command (a member of edltcomsa ), and the error 
occurred in type-in, the pffect is the same as though the user typed 
EDITF(), followed by the atom, i.e. DWIN assumes the user wants to be in 
the editor editing the last thing he referred to. Thus, if the user 
defines the function foo and then types P, he will see -FOO, followed by 
EDIT, followed by the printout associated with the execution of the P 
command, followed by *, at which point he can continue editing foo. 

' dwim userfn =T, DWIN calls dwimuserfn , and if it returns a non-NIL value, 
DWIN returns this value, dwimuserfn is discussed below. 

8. If the unbound atoms occurs in a function, DWIN attempts spelling 
correction using as a spelling list the list of lambda and prog variables 
of the function. 

9. If the unbound atom occurred in a type-in to a break, DWIN attempts 
spelling correction using the lambda and prog variables of the broken 
function. 

10. Otherwise, DWIN attempts spelling correction using spellings3 . 
If all fail, DWIN gives up. 
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Undefined car of Form 



1. If cor of the form is T, DWIN assumes a misplaced T clause and operates as 
described on page 17.8. 

2. If car of the form is F/L, DWIN changes the F/L to 
FUNCTIONCLAMBDA.e.g. (F/L (Y) (PRINT (CAR Y))) is changed to 
(FUNCTION (LAMBDA (Y) (PRINT (CAR Y))). No message is printed and no 
approval requested. If the user omits the variable list, DWIN supplies 
(X)» e.g. (F/L (PRINT (CAR X))) becomes 

(FUNCTION (LAMBDA (X) (PRINT (CAR X)))). DWIN determines that the user has 
supplied the variable list when more than one expression follows F/L, car 
of the first expression is not the nam© of a function, and every element An 
the first expression is atomic. For example, DWIN will supply (X) when 
correcting (F/L (PRINT (CDR X)) (PRINT (CAR X))). 

3* If car of the form is IF, if, or one of the CLISP iterative statement 
operators, e.g. FOR, WHILE, DO et al, the indicated transformation is 
performed, and the result returned as the corrected form. 

4. If car of the form has a function definition, DWIN attempts spelling 
correction on car of the definition using the spelling list 
(LAMBDA NLAMBDA). 

5. If car of the form has an EXPR property, DWIN prints car of the form, 
followed by 'UNSAVED', performs an unsavedef , and continues. No approval 
is requested. 

6. If car of the form has a property FILEDEF, the definition is to be found on 
a file. If the value of the property is atomic, the entire file is to be 
loaded. If a list, car is the name of the file and cdr the relevant 
functions, and loadfns will be used. DWIN first checks to see if the file 
appears in the attached directory, <NEWLISP>'s directory, or <LISP>'s 
directory, and if found, types "SHALL I LOAD" followed by the file name or 
list of functions. If the user approves, DWIN loads the function(s) or 
file, and continues the computation. edita , breakdown , circlmaker , 
cplists , and the pattern match compiler and record capability of CLISP are 
implemented in this fashion. 

7. If CLISP is enabled, and car of the form is part of a CLISP construct, the 
indicated transformation is performed, e.g. (N«-N-l) becomes 
(SETQ N (SUBl N)). 

8. If car of the form contains an 8, DWIN assumes a left parenthesis was 
intended e.g. (C0NS8CAR X). 

9. If car of the form contains a 9, DWIN assumes a right parenthesis was 
intended. 

10. If car of the form is a list, DWIN attempts spelling correction on caer of 
the form using spelling list (LAMBDA NLAMBDA). If successful, DWIN returns 
the corrected expression itself. 

11. If car of the form is a small number, and the error occurred in type-in, 
DWIN assumes the form is really an edit command and operates as described 
in case 6 of unbound atoms. 

12. If car of the form is an edit command (a member of editcomsl ). DWIN 
operates as in 11. 

13. If dwimuserfn sT, dwimuserfn is called* and if it returns a non-NIL value, 
DWIN returns this value. 
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14. If the error occurs In a function, or in a type-in while In a break* DWIN 
checks to see if the last character in car of the form is one of the lambda 
or prog variables, and if the first n-1 characters are the name of a 
defined function, and if so makes the corresponding change, e.g. 
(MEMBERX Y) will be changed to (MEMBER X Y). The protocol followed will be 
the same as for that of spelling correction, e.g. if approvef lfl »T. DWIN 
will type MEMBERX [IN FOO] -> MEMBER X7 

15. Otherwise, DWIN attempts spelling correction using spollingsZ as the 

spelling list. 

If all fail, DWIN gives up. 



Undefined Function in Apply 

1. If the function has a definition, DWIN attempts spelling correction on car 
of the definition using the spelling list (LAMBDA NLAMBDA). 

2. If the function has an EXPR property, DWIN prints its name followed by 
'UNSAVED', performs an unsavedef and continues. No approval is requested. 

3. If the function has a property FILEDEF, DWIN proceeds as in case 6 of 

undefined car of form. 



4. If the error resulted from type-in, and CLISP is enabled, and the function 
name contains a CLISP operator, DWIN performs the indicated transformation, 
e.g. the user types F0O(APPEND FIE FUN). 

5. If the function name contains an 8, DWIN assumes a left parenthesis was 

intended, e.g. E0IT8FOO]. 

6. If the 'function' is a list, DWIN attempts spelling correction on car of 
the list using the spelling list (LAMBDA NLAMBDA). 

7. If the function is a number and the error occurred in type-in, DWIN assumes 
the function is an edit command, and operates as described in case 6 of 
unbound atoms, e.g. the user types (on one line) 3 -1 P. 

8. If the function is the name of an edit command (on either editcomsa or 
editcomsl ) , DWIN operates as in 7, e.g. user types F COND, 

9. If dwimuserfn sT. dwimuserfn is called, and if it returns a non-NIL value, 
this value is treated as the form used to continue the computation. 

10. Otherwise DWIN attempts spelling correction using spellingsl as the 
spelling list, 

11. Otherwise DWIN attempts spelling correction using spellingsZ as the 
spelling list. 

If all fail, DWIN gives up. 
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17.5 DWIHUSERFN 



Pwlmuserfn provides a convenient way of adding to the transformations that OWIN 
perforins, e.g., the user might want to change atoms of the form SX to 
(QA4LbOKUP X). The user defines dwimuserfn as a function of no arguments, and 
then enables it by setting dwimuserfn to T. DWIN will call dwimuserfn before 
attempting spelling correction, but after performing its other transformations, 
e.g. F/L, 8, 9, CLISP, etc. If dwimuserfn returns a non-NIL value, this value 
is treated as a form to be evaluated and returned as the value of faulteval or 
faultapply . Otherwise, if dwimuserfn returns NIL, DWIM proceeds as when 
dwimuserfn is not enabled, and attempts spelling correction. Note that in the 
event that dwimuserfn is to handle the correction, it is also responsible for 
any modifications to the original expression, i.e. OWIN simply takes its value 
and returns it. 

In order for dwimuserfn to be able to function, it needs to know various things 
about the context of the error. Therefore, several of OWIN*s internal 
variables have been made SPECVARS (See Section 18) and are therefore "visible" 
to dwimuserfn . Below are a list of those variables that may be useful. 



faultx for unbound atoms and undefined car of form, 

faultx is the atom or form. For undefined 
functions in apply , faultx is the name of the 
function. 

faultargs for undefined functions in apply , faultargs is the 

list of arguments. 

faultapplyf Ig Is T for undefined functions in apply . (Since 

faultargs may be NIL, faultapplyf Ig is necessary 
to distinguish between unbound atoms and undefined 
function in apply , since faultx is atomic in both 
cases) . 

tail for unbound errors, tail is the tail car of which 

is the unbound atom. Thus dwimuserfn can replace 
the atom by another expression by performing 
(/RPLACA TAIL expr) 

parent for unbound atom errors* parent is the form in 

which the unbound atom appears, i.e. tail is a 
tail of parent . 
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type-in? 



true if error occurred in type-in. 



faultfn 



name of function in which error occurred, 
(f aultfn is TYPE-IN when the error occurred in 
type-in, and EVAL or APPLY when the error occurred 
under an explicit call to EVAL or APPLY). 



dwimifyf Ig 



true if error was encountered during dwinifying as 
opposed to during running the program. 



expr 



definition of faultfn , or argument to eval . I.e. 
the superforiD in which the error occurs. 



17.6 Spelling Corrector Algorithm 

The basic philosophy of DWIN spelling correction is to count the number of 
disagreements between two words, and use this number divided by the length of 
the longer of the two words as a measure of their relative disagreement. One 
minus this number is then the relative agreement or closeness. For example, 
CONS and CONX differ only in their last character. Such substitution errors 
count as one disagreement, so that the two words are in 75% agreement. Nost 
calls to the spelling corrector specify rel s70,^^ so that a single substitution 
error is permitted in words of four characters or longer. However, spelling 
correction on shorter words is possible since certain types of differences such 
as single transpositions are not counted as disagreements. For example, AND 
and NAD have a relative agreement of 100. 

The central function of the spelling corrector is chooz . chooz talces as 
arguments: a word, a spelling list, a minimum relative agreement, and an 
optional functional argument, xword , splst , rel, and fn respectively. 



Integers between 0 and 100 are used instead of numbers between 0 and i in 
order to avoid floating point arithmetic. 

fnsNIL is equivalent to fn::( LAMBDA NIL T). 
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chooz proceeds down splst examining each word. Words not satisfying fn, or 
those obviously too long or too short to be sufficiently close to xword are 
iimnedlately rejected. For example* if rel g70, and xword is 5 characters long, 
words longer than 7 characters will be rejected.^^ 

If tword , the current word on splst . is not rejected, chooz computes the number 
of disagreements between it and xword by calling a subfunctioii,, skor. 

skor operates by scanning both words from left to right one character at a 
time. Characters are considered to agree if they are the same characters; or 
appear on the same teletype key (i.e. a shift mistake), for example, * agrees 
with 1 with ! etc.; or if the character in xword is a lower case version 
of the character in tword . Characters that agree are discarded, and the 
skoring continues on the rest of the characters in xword and tword'. 

If the first character in xword and tword do not agree, skor checks to see if 
either character is the same as one previously encountered, and not accounted- 
for at that time. (In other words, transpositions are not handled by 
lookahead, but by lookback.) A displacement of two or fewer positions is 



Special treatment is necessary for words shorter than xword , since doubled 
letters are not counted as disagreements. For example, CONNSSS and CONS 
have a relative agreement of 100. (Certain teletype diseases actually 
produce this sort of stuttering.) chooz handles this by counting the number 
of doubled characters in xword before it begins scanning splst , and taking 
this into account when deciding whether to reject shorter words. 



skor actually operates on the list of character codes for each word. This 
list is computed by chooz before calling skor using dchcon , so that no 
storage is used by the entire spelling correction process. 



For users on model 33 teletypes, as indicated by the value of model33f Ig 
being T, @ and P appear on the same key, as do L and /, N and L, and 0 and 
and DWIM will proceed accordingly. The initial value for model33flg is 
T, except that various sites override this by use of the username-greeting 
feature described in Section 22. 
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counted as a tranposition; a displacement by more than two positions is counted 
as a disagreement. In either case, both characters are now considered as 
accounted for and are discarded » and scoring continues. 

If the first character in xword and tword do not agree, and neither are equal 
to previously unaccounted-for characters, and tword has more characters 
remaining than xword , skor removes and saves the first character of tword , and 
continues by comparing the rest of tword with xword as described above. If 
tword has the same or fewer chetracters remaining than xword , the procedure is 
the same except that the character is removed from xword . In this case, a 
special check is first made to see if that character is equal to the previous 
character in xword , or to the next character in xword , i.e. a double character 
typo, and if so, the character is considered accounted* for, and not counted as 

30 

a disagreement. 

When skor has finished processing both xword and tword in this fashion, the 
value of skor is the number of unaccounted-for characters, plus the number of 
disagreements, plus the number of tranpositions, with two qualifications: (i) 
If both xword and tword have a character unaccounted-for in the same position, 
the two characters are counted only once, i.e. substitution errors count as 
only one disagreement, not two; and (2) if there are no unaccounted-for 
characters and no disagreements, transpositions are not counted. This permits 
spelling correction on very short words, such as edit commands, e.g. 



Whenever more than two characters in either xword or tword are unaccounted 
for, skoring is aborted, i.e. xword and tword are considered to disagree. 



30 



In this case, the 'length' of xword is also decremented. Otherwise making 
xword sufficiently long by adding double characters would make it be 
arbitrarily close to tword, e.g. XXXXXX would correct to PP. 
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XRT->XTR. 



31 



17,7 DWIM Functions 



dwimCx] 



If X8NIL, disables DWIN; value is NIL. If X"C, 
enables DWIN in cautious mode; value is CAUTIOUS. 
If x*T, enables DWIN in trusting mode; value is 
TRUSTING. For all other values of x> generates an 
error. 



dwimifyCx] 



X is a form or the name of a function, dwimify 
performs all corrections and transformations that 
would occur if x were actually run. dwimify is 
undoable. 



DW 



edit macro, dwimifies current expression. 



addspell[x;splst;n] 



Adds X to one of the four spelling lists as 
follows 

if splst sNIL. adds x to userwords and to 
spellingsZ . Used by defineq . 
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Transpositions are also not counted when fastypef Ig sT, for example, IPULX 
and IPLUS will be in 80X agreement with fastypef Ig sT, only 60X with 
fastypef lg =NIL. The rationale behind this is that transpositions are much 
more common for fast typists, and should not be counted as disagreements, 
whereas more deliberate typists are not as likely to combine tranpositions 
and other mistakes in a single word, and therefore can use more 
conservative metric, fastypef Ig is initially NIL. 

If X is already on the spelling list, and in its temporary section, 
addspell moves X to the front of that section. See page 17.13 for complete 
description of algorithm for maintaining spelling lists. 
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If splst »0, adds x to userwords . Used by load 
whim loading exprs to property lists. 

splst »l, adds X to spellingsl (at end of 
permanent section). Used by lispx . 

splst "2. adds x to spelllngs2 (at end of 
permanent section). Used by lispx . 
If splst «3. adds x to userwords and spellingsa . 

splst can also be a spelling list, in which case n 
is the (optional) length of the temporary section. 

addspell sets lastword to x when splst «Nti. 0 of 
3. 

If X is not a literal atom, addspell takes no 
action. 

misspelled7[xwordirel;splst; fig; tail ;fn] 

If xwordsNIL or alt-mode, misspelled? 
prints s followed by the value of lastword , and 
returns this as the respelling, without asking for 
approval. Otherwise, misspelled? checks to see if 
xwor d is really misspelled, i.e. if fn applied to 
xwor d is true, or xword is already contained on 
spls it. In this case, misspelled? simply returns 
xwor d. Otherwise misspelled? computes and returns 
fixspell[xword;rel;splst;flg;tail;fn]. 
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f ixspellC xword ; rel ; splst ; fig ; tail ; f n T'' 

The value of flxspell is either the respelllng of 
xword or NIL. fixspell perforins all of the 
interactions described earlier, including 
requesting user approval if necessary. 

xword sNIL or S (alt-mode), the respelling is 
the value of lastword ^ and no approval is 
requested. 

If flggWIl, the correction is handled in type-in 
mode, i.e. approval is never requested, and xword 
is not typed. If flggT, xword is typed (before 
the «) and approval is requested if approvef Ig aT. 

If tail is not NIL, and the correction is 
successful, car of tail > is replaced by the 
respelling (using /rplaca ). In addition, fixspell 
will correct misspellings caused by running two 
words together. In this case, car of tail is 
replaced by the two words, and the value of 
fixspell is the first one. For example, if 
fixspell is called to correct the edit command 
(MOVE TO AFTERCONO 3 2) with tail a(AFTERCOND 3 2), 
tail would be changed to (AFTER COND 2 3), and 



33 
34 



fixspell has some additional arguments, for internal use by DWIN. 

In this case, user approval is always requested. In addition, if the first 
word contains either fewer than 3 characters, or fewer characters than the 
second word, the default will be N. 
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flxspell would return AFTER (subject to user 
approval where necessary). 



flxspell generates an error if xword is already on 

splLst . 

The time required for a call to flxspell with a spelling list of length 60 when 
the entire list must be searched is .5 seconds. If fixspell determines that 
the first word on the spelling list is the respelling and does not need to 
search any further, the time required is .02 seconds. In other words, the time 
required is proportional to the number of words with which xword is compared, 
with the time for one comparison, i.e. one call skor> being roughly .01 seconds 
(varies slightly with the number of characters in the words being compared. ) 

The function chooz is provided for users desiring spelling correction without 
any output or interaction: 

chooz[xword;rel;splst;tail;tieflg;fn]^^ The value of chooz is the 

corrected spelling of xword* ^ or NIL; chooz 
performs no interaction and no output. If 
ticflg aT and a tie occurs, i.e. more than one word 
on splst is found with the same closeness, chooz 
returns the first word. If tief Ig aNIL. and a tie 
occurs, chooz returns NIL. 



If tail =T, fixspell will also perform run-on corrections, returning a 
dotted pair of the two words in the event the correction is of this type. 

chooz has some additional arguments, for internal use by DWIN. 

chooz does not perform spelling completion, only spelling correct4.on. 
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If tilll Is not NIL, chooz will correct a 
misspelling consisting of running two words 
together, e.g. (BREAKFOO) for (BREAK FOO). The 
value of chooz in this case is a dotted pair of 
the two words, e.g. (BREAK . FOO). Both DWIN and 
the editor use this option. 

fncheck[fn;noioessflg;spellflg] The task of fncheck is to check whether fn is 

the name of a function and if not, to correct its 
spelling.^* If fn is the name of a function or 
spelling correction is successful, fncheck adds 
the (corrected) name of the function to userwords 
using addspell , and returns it as its value. 

nomessf Ig informs fncheck whether or not the 
calling function wants to handle the unsuccessful 
case; if nomessflg is T, fncheck simply returns 
NIL, otherwise it prints fn NOT A FUNCTION and 
generates a non-breaking error. 

fncheck calls misspelled? to perform spelling 
correction, so that if jQisNIL, the value of 
lastword will be returned, spellf Ig corresponds 
to misspelled? 's fourth argument, fig . If 
spellf Ig sT, approval will be asked if DWII1 was 
enabled in CAUTIOUS mode, i.e. if approvef lg «T. 



da 



Since fncheck is called by many low level functions such as arglist , 
unsavedef, etc., spelling correction only takes place when dwlmf Ig sT, so 
that these functions can operate in a small INTERLISP system which does not 
contain DWIN. 
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fncheck is currently used by arglist . unsavedef , prettyprlnt , breakO , breakin , 
chngnm , advise , printstructure , f Irstfn , lastfn , calls , and edlta . For 
example, breakO calls fncheck with nomessf Ig ^T since if fncheck cannot produce 
a function, breakO wants to define a dummy one. printstructure however calls 
fncheck with nomessf Ig sNIL, since it cannot operate without a function. 

Many other system functions call misspelled? or fixspell directly. For 
example, break 1 calls fixspell on unrecognized atomic Inputs before attem0tlng 
to evaluate them, using as a spelling list a list of all break commands. 
Similarly, lispx calls fixspell on atomic Inputs using a list of all llspx 
commands. When unbreak is given the name of a function that is not broken, it 
calls fixspell with two different spelling lists, first with brokenfns , and if 
that falls, with userwords. makefile calls misspelled? using filelst as a 
spelling list. Finally, load , bcompl , brecompile , tcompl , and recompile all 
call misspelled ? if their input flle(s) won't open. 
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SECTION 18 
THE COMPILER AND ASSEMBLER 



18.1 The Compiler 

The compiler is available in the standard INTERLISP system. It may be used to 
compile individual functions as requested or all function definitions in a 
standard format LOAD file. The resulting code may be stored as it is compiled, 
so as to be available for immediate use, or it may be written onto a file for 
subsequent loading. The compiler also provides a means of specifying sequences 
of machine instructions via ASSEMBLE. 

The roost common way to use the compiler is to compile from a symbolic 
( prettydef ) file, producing a corresponding file which contains a set of 
functions in compiled form which can be quickly loaded. An alternate way of 
using the compiler is to compile from functions already defined in the user's 
INTERLISP system. In this case, the user has the option of specifying whether 
the code is to be saved on a file for subsequent loading, or the functions 
redefined, or both. In either case, the compiler will ask the user certain 
questions concerning the compilation. The first question is: 



The compiler itself, i.e. the part that actually generates code, was 
written and documented by, and is the responsibility of A.K. Hartley. The 
user interfaces, i.e. tcompl . . recompile , bcompl . and brecompile , were 
written by W. Teitelman. 
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LISTING? 



The answer to this question controls the generation of a listing and is 
explained in full below. However, for most applications, the user will want to 
answer this question with either ST or F, which will also specify an answer to 
the rest of the questions which would otherwise be asked. ST means the user 
wants the compiler to STore the new definitions; F means the user is only 
interested in compiling to a File, and no storing of definitions is performed. 
In both cases, the compiler will then ask the user one more question: 

OUTPUT FILE: 

to which the user can answer: 

N or NIL no output file. 

File name file is opened if not already opened, and compiled code 
is written on the file. 

Example: 

*-COMPILE((FACT FACTl FACT2)) 
LISTING? ST 
OUTPUT FILE: FACT.COH 
(FACT COMPILING) 

(FACT REDEFINED)^ 



(FACT2 REDEFINED) 
(FACT FACTl FACT2) 



compiler output and error messages are explained on page 18.46~52. 
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this process caused the functions FACT, FACTl, end FACT2 to be compiled, 
redefined, and the conpiled definitions also written on the file FACT.COM for 
subsequent loading. 

16.2 Compiler Questions 

The compiler uses the free variables lapflfl , strf. svflg . Icfil and Istf il 
which determines various modes of operation. These variables are set by the 
answers to the 'compset' questions. When any of the top level compiling 
functions are called, the function compset is called which asks a number of 
questions. Those that can be answered 'yes' or 'no' can be answered with YES, 
Y, or T for YES; and NO, N, or NIL for NO. The questions are: 

1. LISTING? 

The answer to this question controls the generation of a listing. Possible 
answers are: 

3 

Prints output of pass 1, the LAP macro code. 
Prints output of pass 2, the machine code. 
Prints output of both passes. 
Prints no listings. 

The variable lapflg is set to the answer. If the answer is affirmative, 
compset will type FILE: to allow the user to indicate where the output is to be 
written. The variable Istfil is set to the answer. 



i 

2 

YES 
NO 



The LAP and machine code are usually not of interest but can be helpful in 
debugging macros. 
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There are three other possible answers to LISTING? * each of vrhich specifies a 
complete mode for compiling. They are: 



S 



Same as last setting. 



F 



Compile to File (no definition of functions). 



ST 



STore new definitions. 



Implicit in these three are the answers to the questions on disposition of 
compiled code and expr's» so questions 2 and 3 would not be asked If 1 were 
answered with S, F» or ST. 



2. REDEFINE? 



YES Causes each function to be redefined as it is compiled. The 
compiled code is stored and the function definition changed. 
The variable strf is set to T. 



NO Causes function definitions to remain unchanged. The variable 
strf is set to NIL. 



The answer ST for the first question implies YES for this question, F Implies 
NO, and S makes no change. 



If answered YES, svf Ig is set to T, and the exprs are saved on the property 
list of the function name. Otherwise they are discarded. The answer ST for 
the first question implies YES for this question, F implies NO, and S makes no 
change . 



3. 



SAVE EXPRS? 
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4. OUTPUT FILE: 



If the compiled definitions are to be written for later loading, you should 
provide the name of a file on which you wish to save the code that is 
generated. If you answer T or TTY:, the output will be typed on the teletype 
(not particularly useful). If you answer N» NO, or NIL, output will not be 
done. If the file named is already open, it will continue to be used. The 
free variable Icf il is set to the name of the file. 

18.3 Nlambdas 

When compiling the call to a function, the compiler must prepare the arguments 
to the function in one of three ways: 

1. Evaluated (SUBR, SUBR*. EXPR, EXPR*. CEXPR. CEXPR*) 

2. Unevaluated, spread (FSUBR, FEXPR, CFEXPR) 

3. Unevaluated, not spread (FSUBR*, FEXPR*, CFEXPR*) 

In attempting to determine which of these three is appropriate, the compiler 
will first look for a definition among the functions in the file that is being 
compiled. If the function is not contained there, the compiler will look, for 
other information which can be supplied by the user by including nlarobda 
nospread functions on the list nlama (for n lam bda atoms), and including nlambda 
spread functions on the list nlaml (for nlarob da list), and including lambda 
functions on the list lams .^ If the function is not contained in the file,^ or 



Including functions on lams is only necessary to override in-core nlambda 
definitions, since in the absence of other information, the compiler 
assumes the function is a lambda. 

The function can be defined anywhere in any of the files given as arguments 
to bcompl , tcompl . brecompile or recompile . 
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on the list nlama , nlaml , or lams , the compiler will look for a current 
definition. If the function is defined, its function type is assumed to be the 
desired type. If it is not defined, the compiler assumes that the function is 
of type 1, i.e. its arguments are to be evaluated. In other words, if there 
are type 2 or 3 functions called from the functions being compiled, and they 
are only defined in a separate file, they must be included on nlama or nlarol , 
or the compiler will incorrectly assume that their arguments are to be 
evaluated, and compile the calling function correspondingly. Note that this is 
only necessary if the compiler does not 'know' about the function. If the 
function is defined at compile time, or is handled via a macro, or is contained 
in the same group of files as the functions that call it, the compiler will 
automatically handle calls to that function correctly. 
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Another top level free variable that affects compilations is globalvars . Any 
variables that appear on the list globalvars , and are used freely in a compiled 
function, are always accessed through their value cell. In other words, a 
reference to the value of this variable is equivalent to 
(CAR (QUOTE variable)), regardless of whether or not it appears on the stack. 



Before making this assumption, if the value of compileuserfn is not NIL, 
the compiler calls (the value of) compileuserfn giving it as arguments cdr 
of the form and the form itself, i.e. the compiler does 
(APPLY* COMPILEUSERFN (COR form) form). If a non-NIL value is returned, it 
is compiled instead of form. If NIL is returned, the compiler compiles the 
original expression as a call to a lambda-spread that is not yet defined. 
CLISP (Section 23) uses compileuserfn to tell the compiler how to compile 
iterative statements, IF-THEN-ELSE statements, and pattern match 
constructs. 



The names of functions so treated are added to the list alams 
(for assumed lam das) . alams is not used by the compiler; it is maintained 
for the user's benefit, i.e. so that the user can check to see whether any 
incorrect assumptions were made. 
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i.e., the stack is not even searched for this variable when the compiled 
function is entered. Similarly, (SETQ variable value) is equivalent to 
(RPLACA (QUOTE variable) value); i.e., it sets the top-level value. 

All system parameters, unless otherwise specified, are 6L0BALVARS, i.e. are 
members of the list globalvars , e.g. brokenfns , editmacros , #rpars , dwimf Ig , et 
al.*" Thus, rebinding these variables will not affect the behavior of the 
system: instead, the variables must be re^et to their new values, and if they 
are to be restored to their original values, reset again. For example, the 
user might write ...(SETQ globalvar new-value) form (SETQ globalvar old-value). 
Note that in this case, if an error occurred during the evaluation of form , or 
a control-D was typed, the global variable would not be restored to its 
original value. The function resetvar (described in Section 5) provides a 
convenient way of resetting global variables in such a way that their values 
are restored even if an error occurred or control-0 is typed. 

18.5 Compiler Functions 

Note: when a function is compiled from its in core definition, i.e., via 
compile (and certain calls to recompile ), as opposed to tcompl (which uses the 
definitions on a file), and the function has been modified by break , trace , 
breakin , or advise , it is restored to its original state, and a message printed 
out, e.g., FOO UNBROKEN. Then, if the function is not defined as an expr, its 
property list is searched for the property EXPR (see savedef , Section 8). If 
there is a property EXPR, its value is used for the compilation, otherwise, the 
compiler prints (fn NOT COMPILEABLE), and goes on to the next function. 



Since the stack does not have to be searched to find the values of these 
variables, a considerable savings in time is achieved, especially for deep 
computations . 
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coinpileCx;flg] x Is a list of functions (if atomic, list[x] is 

used), compile first asks the standard compiler 
questions, and then compiles each function on Xf 
using its in-core definition. Value is x* 

If compiled definitions are being dumped to a 
file, the file is closed unless f lfl «T. 

o 

coropilel[nameidef ] compiles def, redefining name if strf«T. compilel 

is used by compile , tcompl . and recompile . If 
dwimifycompflg is T, or def contains a CLISP 
declaration, def is dwimified before compiling. 
See Section 23. 

tcomplC files] tcompl is used to 'compile files', i.e., given a 

symbolic load file (e.g., one created by 
prettydef ), it produces a file that contains the 
same S-expressions as the original symbolic file, 
except that every defineq is replaced by the 
corresponding compiled definitions. This 
'compiled' file can be loaded into any INTERLISP 
system with load. 

files is a list of symbolic files to be compiled 
(if atomic, list[files] is used), tcompl asks the 
standard compiler questions, except for 
OUTPUT FILE: Instead, the output from the 
compilation of each symbolic file is written on a 



strf is one of the variables set by compset . described earlier. 
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file of the sarae name suffixed with COH, e.g., 
tcompl[(SYNl SVH2)] produces two files, SYNl.CON 
and SYH2.C0M.^^ 

tcompl processes each file one at a time, reading 
in the entire file. Then, for each DEFINEQ, 
tcompl adds any NLAMBDA's in the DEFINEQ to nlama 
or nlanil * and adds lambdas to the list lams ,* 
so that calls to these functions will be compiled 
correctly. Expressions beginning with DECLARE can 
be used to affect the compilation, e.g. set up 
NACROS. tcompl evaluates each expression in ( cdr 

IS 

of) the DECLARE, presumably for effect.*" tcompl 
then compiles each function in the DEFINEQ 's. 
Finally, all other expressions in the file, e.g. 
RPAQQ*s, DEFLIST*s, etc., are written onto the 
output file.^^ 



The file name is constructed from the name field only, e.g. 
tcompl[<B0BR0W>F00.TEM;3] produces F00.COM on the connected directory. The 
version number will be the standard default. 



11 
12 
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described earlier, page 18.5. 

nlama, nlaml , and lams are rebound to their top level values (using 
resetvar ) by tcompl , recompile , bcompl , brecompile , compile , and 
blockcompile , so that any additions to these lists while inside of these 
functions will not propagate outside. 

DECLARE is defined the same as QUOTE, so it will have no effect when the 
symbolic file is loaded, tcompl , recompile , bcompl , and brecompile also 
evaluate any DEFLIST expression that was output by a COMPROP or COMPROP* 
prettydef command (see Section 14). 

except for OEFLISTs output by a COMPROP* prettydef command. 
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The value of tcompl is a list of the names of the 
output files. All files are properly terminated 
and closed. 

Recompile 

The purpose of recompile is to allow the user to update a compiled file without 
recompiling every function in the file. Recompile does this by using the 
results of a previous compilation. It produces a compiled file similar to one 
that would have been produced by tcompl . but at a considerable savings in time 
by compiling selected functions and copying from an earlier tcompl or recompile 
file the compiled definitions for the remainder of the functions in the file. 
Even more savings can be achieved if the symbolic file being recompiled is 
currently in-core, i.e., was previously loaded, or was made from the user's 
current system. In this case, recompile will not have to read in the file, but 
can work from the in-core definitions.^^ 

If the functions to be recompiled are currently defined as exprs, then 
recompile can be called with just one argument, the symbolic file; the rest of 
the arguments will be set appropriately. In other words, the most common usage 
of recompile is in the following sequence, loadC file; PROP], edit some functions 
(thus unsavedef ing them), roakefile[file], and recompile[f ile], producing a new 
compiled file exactly equivalent to tcompl[file]. The rest of the discussion 
of recompile explains nonstandard usages, e.g., the symbolic file has not been 
loaded, some of the functions that have been changed are currently not unsaved, 
etc. 



This requires that the user observe the conventions of the 'file package' 
described in Section 14 when making the symbolic file, i.e., he used 
makefile or else used prettydef with arguments of the form fileFNS, file, 
and fileVARS. 
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recoapile[pfile;cfil«;fns;coref Ig] pflle is the name of the pretty file to 

be conpiled, cf lie is the name of the compiled 
file containing compiled definitions that may be 
copied, fns is a list of the functions in pf ile 
that are to be recompiled* i.e.» they have been 
chariged (or defined for the first time) since 
cf ile was made. Note that pfile , not fns, drives 
recompile , so that extra functions may appear on 
fns . If fnssT, all function in pf ile currently 
defined as exprs (after unbreaking and unadvising) 
are recompiled. 

recompile asks the standard compiler questions, 

except for OUTPUT FILE: As with tcompl , the output 

1ft 

automatically goes to pf ile. COM . recompile then 
reads in pf ile . As with tcompl , for each DEFINEQ, 
the NLAMBDAs are added to nlama and nlaml , and 
LAMBOAs are added to lams . Similarly, DECLARES 
and DEFLISTs are treated the same as with tcompl . 
Then each function is compiled if it appears on 
fns , or fns«T and the function is an expr . 
Otherwise, recompile reads from cf ile until it 
finds the compiled version of the function it is 
working on, and then copies it (and all compiler 
generated subfunctions) to pfile.COM . Finally, 
all other expressions are written onto pfile.COM . 



In general, all constructions of the form pfile.COM, pfileFNS, and 
pfileVARS are performed using the name field only. For example, if 
pf ile a<B0BR0W>F00.TEM;3. pfile.COM means FOO.CON, pfileFNS means FOOFNS, 
etc . 
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Note that the user can thus modify an old compiled file so as ^td add n^w ' 
functions by prettydefing them in pfile and then including them on fns. 
Similarly, he can delete functions by simply not prettydefing them, since if 
they do not appear in pfile , they will never be compiled or copied to 
pfile.COM . Note, however that the entire process depends on the order of those 
functions in cfile that are to be copied being the same as those in pfile . For 
example, if FOO appears before FIE in cfile , but the order is reversed in 
pfile , then when recompile attempts to copy FIE, it will skip over FOO. Then 
when it attempts to copy FOO, it will read to the end of cfile and not find it. 
In this case, it will generate an error FOO NOT FOUND. 

If the file pfile is in core, i.e., has been 
loaded, or else was prettydef ed from this system, , 
the user can take advantage of this by calling 
recompile with coreflg =T. In this case, the 
procedure is the same as described above, but 
recompile 'fakes' reading pfile , instead 
determining what is on pfile from pfilefns and 

17 

pf ilevars ( recompile does read the date from 
pfile . which it copies to the output file.) 

recompile will work correctly even for functions 
written via the third argument to prettydef using 
a FNS command. (See Section 14). 

If cfile «NIL. pfile.COM is used for copying 



17 ^ 

See footnote on page 18.11. 
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Srom* In addition, if both fns and coreflg are 
NIL. they are set to T. This is the most common 
usage. 

The value of recompile is the new compiled file, 
pfileXOH . 



18.6 Open Functions 

When a function is called from a compiled function, a system routine is invoked 
that sets up the parameter and control push lists as necessary for variable 
bindings and return Information. As a result, function calls can take up to 
350 microseconds per call. If the amount of time spent inside the function is 
small, this function calling time will be a significant percentage of the total 
time required to use the function. Therefore, many 'small' functions, e.g., 
car , cdr, e5[, not, cons are always compiled 'open', i.e., they do not result in 
a function call. Other larger functions such as prog , selectq , mapc , etc. are 
compiled open because they are frequently used. It is useful to know exactly 
which functions are compiled open in order to determine where a program is 
spending its time. Therefore below is a list of those functions which when 
compiled do not result in function calls. Note that the next section tells how 
the user can make other functions compile open via MACRO definitions. 
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In other words, if cf lie , the file used for obtaining compiled definitions 
to be copied, is NIL, pfile.COM is used, i.e., same name as output but a 
different version number (one less) than the output file. 

The user can also affect the compiled code via compileuserfn , described in 
footnote on page 16.6. 
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The following functions compile open: 

AC. ADDl, AND. APPLY*, ARG, ARRAYP. ASSEMBLE. ATOM, BLKAPPLY, BLKAPPLY*, CAR, 
COR, CAAR, ... CDDOAR, CODDDR, CLOSER, COND, CONS, E0» ERSETQ, EVERY, EVQ, 
FASSOC, FCHARACTER, FOIFFERENCE, FGTP, FIX, FIXP. FLAST, FLENGTH, FLOAT, 
FLOATP, FMEMB. FMINUS, FNTH, FPLUS, FQUOTIENT, FRPLACA, FRPLACO, FSTKARG, 
FSTKNTH. FTIMES, FUNCTION, GETHASH, GO, lOIFFERENCE, IGREATERP, ILESSP. IMINUS, 
IPLUS, IQUOTIENT, IREMAINOER, ITIMES, LIST, LISTP, LITATOM, LLSH. LOC. LOGANO, 
LOGOR. LOGXOR, LRSH. LSH. MAP, MAPC, MAPCAR. MAPCON, MAPCONC, MAPLIST, MINUSP, 
NEQ, NLISTP. NLSETQ. NOT, NOTEVERY. NOTANY, NULL. NUMBERP. OPENR, OR, PROG, 
PROGl, PROGN, RESETFORM, RESETVAR, RETURN, RPTQ, RSH, SELECTQ, SETAR6, SETN, 
SETQ, SMALLP, SOME, STRINGP, SUBIl, SUBSET, UNOONLSETQ, VA6, ZEROP 

18.7 Compiler Macros 

The INTERLISP compiler includes a macro capability by which the user can affect 

the compiled code. Macros are defined by placing the macro definition on the 

20 

property list of the corresponding function under the property MACRO. When 
the compiler begins compiling a form, it retrieves a macro definition for car 
of the form, if any, and uses it to direct the compilation. The three 
different types of macro definitions are given below. 



An expression of the form (DECLARE (DEFLIST ... (QUOTE MACRO))) can be used 
within a function to define a MACRO. DECLARE is defined the same as QUOTE 
and thus can be placed so as to have no effect on the running of the 
function. 



The compiler has built into it how to compile certain basic functions such 
as car , prog , etc., so that these will not be affected by macro 
definitions. These functions are listed above. However, some of them are 
themselves implemented via macros, so that the user could change the way 
they compile. 
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(1) Open macros - (LAMBDA ...) or (NLAMBOA ...) 

A function can be made to compile open by giving it a macro definition of the 
form (LAMBDA ...) or (NLAMBDA ...), e.g., 

(LAMBDA (X) (COND ((GREATERP X 0) X) (T (MINUS X)))) for abs. The effect is 
the same as though the macro definition were written in place of the function 
wherever it appears in a function being compiled, i.e., it compiles as an open 
LAMBDA or NLAMBDA expression. This saves the time necessary to call the 
function at the price of more compiled code generated. 

(2) Computed macros - (atom expression) 

A macro definition beginning with an atom other than LAMBDA, NLAMBDA, or NIL, 
allows computation of the INTERLISP expression that is to be compiled in place 
of the form. The atom which starts the macro definition is bound to cdr of the 
form being compiled. The expression following the atom is then evaluated, and 
the result of this evaluation is compiled in place of the form. For example, 
list could be compiled this way by giving it the macro definition: 

[X (LIST (QUOTE CONS) 
(CAR X) 
(AND (CDR X) 

(CONS (QUOTE LIST) 
(CDR X] 

This would cause (LIST X Y Z) to compile as (CONS X (CONS Y (CONS Z NIL))). 
Note the recursion in the macro expansion .^^ Ersetq , nlsetq , map , mapc, mapcar , 
mapconc , and some, are compiled via macro definitions of this type. 

If the result of the evaluation is the atom INSTRUCTIONS, no code will be 
generated by the compiler. It is then assumed the evaluation was done for 
effect and the necessary code, if any, has been added. This is a way of giving 
direct instructions to the compiler if you understand it. 



list is actually compiled more efficiently. 
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(3) Substitution macro - (NIL expression) or (list expression) 

Each argument in the form being compiled is substituted for the corresponding 
atom in car of the macro definition, and the result of the substitution is 
compiled instead of the form, i.e., 

(SUBPAIR (CAR macrodef) (CDR form) (CAOR macrodef)). For example, the macro 
definition of addl is ((X) (IPLUS X 1)). Thus, (ADDl (CAR Y)) is compiled as 
(IPLUS (CAR Y) 1). The function!; addl , subl, nea, nlistp . zerop , f length , 
fmemb , fassoc , f last , and fnth are all compiled open using substitution macros. 
Note that abs could be compiled open as shown earlier or via a substitution 
macro. A substitution macro, however, would cause (ABS (FOO X)) to compile as 
(CONO ((GREATERP (FOO X) 0) (FOO X)) (T (NINUS (FOO X)))) and consequently 
(FOO X) would be evaluated three times. 

18.8 FUNCTION and Functional Arguments 

Expressions that begin with FUNCTION will always be compiled as separate 
functions named by attaching a gensym to the end of the name of the function 
in which they appear, e.g., FOOA0003.^^ This gensym function will be called at 
run time. Thus if FOO is defined as 

(LAMBDA (X) ... (FOOl X (FUNCTION ...)) ...) and compiled, then when FOO is 
run, FOOl will be called with two arguments, X, and FOOAOOOn,^^ and then FOOl 
will call FOOAOOOn each time it must use its functional argument. 



except when they are compiled open, as is the case with most of the mapping 
functions. 

nlsetq and ersetq expressions also compile using gensym functions. As a 
result, a ^ or return cannot be used inside of a compiled nlsetq or ersetq 
if the corresponding prog is outside, i.e. above the nlsetq or ersetq . 

or an appropriate funarg expression, see Section 11. 
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Note that a considerable savings in tine could be achieved by defining FOOl as 
a computed macro of the form: 

(Z (LIST (SUBST (CAOADR Z) (QUOTE FN) def) (CAR Z))) 

where def is the definition of FOOl as a function of Just its first argument 
and FN is the name used for its functional argument in its definition. The 
expression compiled contains what was previously the functional argument to 
FOOl, as an open LAMBDA expression. Thus you save not only the function call 
to FOOl, but also each of the function calls to its functional argument. For 
example, if FOOl operates on a list of length ten, eleven function calls will 
be saved. Of course, this savings in time cost space, and the user must decide 
which is more important. 

18.9 Block Compiling 

Block compiling provides a way of compiling several functions into a single 
block. Function calls between the component functions of the block are very 
fast, and the price of using a free variable, namely the time required to look 
up its value on the stack, is paid only once - when the block is entered. 
Thus, compiling a block consisting of Just a single recursive function may be 
yield great savings if the function calls itself many times, e.g., equal , copy , 
and count are block compiled in INTERLISP. 

The output of a block compilation is a single, usually large, function. This 
function looks like any other compiled function; it can be broken, advised, 
« printstructured, etc. Calls from within the block to functions outside of the 
block look like regular function calls, except that they are usually linked 
(described below). A block can be entered via several different functions. 
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called entries. These must be specified when the block is compiled. For 
example, the error block has three entries, errorx . interrupt , and faultl . 
Similarly, the compiler block has nine entries. 

Specvars 

One savings in block compiled functions results from not having to store on the 
stack the names of the variables bound within the block, since the block 
functions all 'know* where the variables are stored. However, if a variable 
bound in a block is to be referenced outside the block, it roust be included on 
the list specvars . For example, helpclock is on specvars , since it is rebound 
inside of lispxblock and editblock . but the error functions must be able to 
obtain its latest value. 

Localfreevars 

Localfreevars is a feature designed for those variables which are used freely 
by one or more of the block functions, but which are always bound (by some 
other block function) before they are referenced, i.e. their free values above 
the block are never used. Normally, when a block is entered, all variables 
which are used freely by any function in the block are looked up and pointers 
to the bindings are stored on the stack. When any of these variables are 



Actually the block is entered the same as every other function, i.e., at 
the top. However, the entry functions call the main block with their name 
as one of its arguments, and the block dispatches on the name, and jumps to 
the portion of the block corresponding to that entry point. The effect is 
thus the same as though there were several different entry points. 



Arguments to the block that are referenced freely outside the block must 
also be SPECVARS if they are reset within the block, or else the new value 
will not be obtained. 
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rebound in the block, the old pointer is saved and a pointer to the new binding 
is stored in the original stack position. It frequently happens that variables 
used freely within a block are in fact always bound within the block prior to 
the free reference. The unnecessary lookup of the value of the free variable 
at the time of entry to the block can be avoided by putting the variable name 
on the list localfreevars . If a variable is on localfreevars , its value will 
not be looked up at the time of entry. When the variable is bound, the value 
will be stored in the proper stack position. Should the variable in fact be 
referenced before it is bound, the program will still work correctly. 
Invisible to the user, a rather time-comsuming process will take place. The 
reference will cause a trap which will invoke code to determine which variable 
was referenced and look up the value. Future references to that variable 
during this call to the block will be, normal, i.e. will not cause a trap. 

trapcount[x] is a function to monitor the performance of block 

compiled code with respect to localfreevars . If x 
is NIL, trapcount returns the cumulative number of 
traps caused by localfreevars that were not bound 
before use. If x is a number, the trapcount is 
reset to that number. 

evq is another compiler artifice for free variables references. (EVQ X) has 
the effect of (EVAL (QUOTE X)) without the call to aval (if X is an atom), evq 
is intended primarily for use in conjunction with localfreevars . For example, 
suppose a block consists of three functions, FOOl, F002, and F003, with FOOl 
and fOOZ being entries, and F003 using X freely, where X is bound in FOOl, but 
not in F002, i.e. FOOl rebinds X, but when entered via F002, the user intends X 
to be used freely, and its higher value obtained. If X is on localfreevars , 
then each time the block is entered via F002, a trap will occur when F003 first 
references X. In order to avoid this, the user can insert (EVQ X) in F002. 
This will circumvent the trap by explicitly invoking the routine that searches 
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back up the stack for the last binding of X. Thus, when used with 
localfreevars , evq does two things: it returns the value of its argument, and 
also stores that value in the binding slot for the variable so that no future 
references to that variable (in this call) will cause traps. Since the time 
consumed by the trap can greatly exceed the time required for a variable 
lookup, using ey£ in these situations can result in a considerable savings. 

Retfns 

Another savings in block compilation arises from omitting most of the 
information on the stack about internal calls between functions in the block. 
However, if a function's name must be visible on the stack, e.g., if the 
function is to be returned from retfroro . it must be included on the list 
retfns . 

Blkapplyfns 

Normally, a call to apply from inside a block would be the same as a call to 
any other function outside of the block. If the first argument to apply turned 
out to be one of the entries to the block, the block would have to be 
reentered, blkapplyfns enables a program to compute the name of a function in 
the block to be called next, without the overhead of leaving the block and 
reentering it. This is done by including on the list blkapplyfns those 
functions which will be called in this fashion, and by using blkapply in place 
of apply , and blkapply* in place of apply* . For example, the calls to the 
functions handling RI, RO, LI, LO, BI, and BO in the editor are handled this 
way. If blkapply or blkapply* is given a function not on blkapplyfns , the 
effect is the same as a call to apply or apply* and no error is generated. 
Note however, that blkapplyfns must be set at compile time, not run time, and 
furthermore, that all functions on blkapplyfns must be in the block, or an 
error is generated (at compile time), NOT ON BLKFNS. 
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BXklibrary 



Compiling a function open via a macro provides a way of eliminating a function 
call. For block compiling, the same effect can be achieved by including the 
function in the block. A further advantage is that the code for this function 
will appear only once in the block, whereas when a function is compiled open, 
its code appears at each place where it is called. 

The block library feature provides a convenient way of including functions in a 
block. It is Just a convenience since the user can always achieve the same 
effect by specifying the function(s) in question as one of the block functions, 
provided it has an expr definition at compile time. The block library feature 
simply eliminates the burden of supplying this definition. 

To use the block library feature, place the names of the functions of interest 
on the list blklibrary , and their EXPR definition on the property list of the 
function under the property iBLKLIBRARYOEF. When the block compiler compiles a 
form, it first check to see if the function being called is one of the block 
functions. If not, and the function is on blklibrary , its definition is 
obtained from the property value of BLKLIBRARYDEF, and it is automatically 
included as part of the block. The functions assoc, equal , getp , last, length , 
lispxmatch , memb , nconcl, nljeft, nth , and /rplnode already have BLKLIBRARYDEF 
properties. 

18.10 Linked Function Calls 

Conventional (non-linked) function calls from a compiled function go through 
the function definition cell;, i.e., the definition of the called function is 
obtained from its function definition cell at call time. Thus, when the user 
breaks, advises, or otherwise modifies the definition of the function FOO, 
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every function that subsequently calls it instead calls the modified function. 
For calls from the system functions, this is clearly not a feature. For 
example, the user may wish to break on basic functions such as print , eval , 
rplaca , etc., which are used by the break package. In other words, we would 
like to guarantee that the system packages will survive through user 
modification (or destruction) of basic functions (unless the user specifically 
requests that the system packages also be modified). This protection is 
achieved by linked function calls. 

For linked function calls, the definition of the called function is obtained at 
link time, i.e., when the calling function is defined, and stored in the 
literal table of the calling function. At call time, this definition is 
retrieved from where it was stored in the literal table, not from the function 
definition cell of the called function as it is for non-linked calls. These 
two different types of calls are illustrated in Figure 18-1. 

Note that while function calls from block compiled functions are usually 
linked, and those from standardly compiled functions are usually non-linked, 
linking function calls and blockcompiling are independent features of the 
INTERLISP compiler, i.e., linked function calls are possible, and frequently 
employed, from standardly compiled functions. 
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Note that normal function calls require only the called function's name in the 
literals of the compiled code, whereas a linked function call uses two literals 
and hence produces slightly larger compiled functions. 

The compiler's decision as to whether to link a particular function call is 
determined by the variables linkfns and nolinkfns as follows: 



If the function appears on nolinkfns , the call is not linked; 
If block compiling and the function is one of the block functions, the 
call is internal as described earlier; 
If the function appears on linkfns , the call is linked; 
If nolinkfns gT, the call is not linked; 
If block compiling, the call is linked; 
If linkfns sT. the call Is linked; 
Otherwise the call is not linked. 

Note that (1) takes precedence over (2), i.e., if a function appears on 
nolinkfns , the call to it is not linked, even if it is one of the functions in 
the block, i.e., the call will go outside of the block. 

Nolinkfns is initialized to various system functions such as error set , breakl, 
etc. Linkfns is initialized to NIL. Thus if the user does not specify 
otherwise, all calls from a block compiled function (except for those to 
functions on nolinkfns ) will b« linked; all calls from standardly compiled 
functions will not be linked. However, when compiling system functions such as 
help , error, arglist , fntyp . breakl , et al, linkfns is set to T so that even 
though these functions are not block compiled, all of their calls will be 
linked. 

If a function is not defined at link time, i.e., when an attempt is made to 
link to it, a message is printed, fnl NOT DEFINED WHEN LINK TRIED FROM fn2. 



(1) 
(2) 

(3) 
(4) 
(5) 
(6) 
(7) 
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When the function is later defined, the link can be completed by relinking the 
calling function using relink described below. Otherwise, if a function is run 
which attempts a linked call that was not completed, faultapply is called. If 
the function is now defined, i.e., it was defined at some point after the 
attempt was made to link to it, faultapply will quietly perform the link and 
continue the call. Otherwise, it will print U.O.F. and proceed as described in 
Section 16. 

Linked function calls are printed on the backtrace as ;fn; where fn is the name 
of the function. Note that this name does not actually appear on the stack, 
and that stkpos , ret from , and the rest of the pushdown list functions (Section 
12) will not be able to find it. Functions which must be visible on the stack 
should not be linked to, i.e., include them on nolinkfns when compiling a 
function that would otherwise link its calls. 

printstructure . calls , break on fnl-IN-fn2 and advise fnl-IN-fn2 all work 
correctly for linked functions calls, e.g., break[(FOO IN FIE)], where FOO is 
called from FIE via a linked function call. 

Relinking 

The function relink is available for relinking a compiled function, i.e., 
updating all of its linked c<ills so that they use the definition extant at the 
time of the relink operation. 

relinkCfn] fn is either WORLD, the name of a function, a list 

of functions, or an atom whose value is a list of 
functions* relink performs the corresponding 
relinking operations. relink[WORLD] is possible 
because laprd maintains on linkedfns a list of all 
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user functions containing any linked calls. 
syslinkedfns is a list of all system functions 
that have any linked calls. relink[ WORLD] 
performs both relink[linkedfns] and 
relinkC syslinkedfns]. 

The value of relink is fn. 

It is important to stress that linking takes place when a function is defined. 
Thus, if FOO calls FIE via a linked call, and a bug is found in FIE, changing 
FIE is not sufficient; FOO must be relinked. Similarly, if FOOl, F002, and 
F003 are defined (in that order) in a file, and each call the others via linked 
calls, when a new version of the file is loaded, FOOl will be linked to the old 
F002 and F003, since those definitions will be extant at the time it is read 
and defined. Similarly, F002 will link to the new FOOl and old F003. Only 
F003 will link to the new FOOl and F002. The user would have to perform 
relink[FOOFNS] following the load. 

18.11 The Block Compiler 

There are three user level functions for blockcompiling, blockcompile , bcompl , 
and brecompile , corresponding to compile , tcompl , and recompile . All of them 
ultimately call the same low level functions in the compiler, i.e., there is no 
'blockcompiler ' per se. Instead, when blockcompiling, a flag is set to enable 
special treatment for specvars , retfns, blkapplyfns , and for determining 
whether or not to link a function call. Note that all of the previous remarks 
on macros, globalvars, compiler messages, etc., all apply equally for block 
compiling. Using block declarations described below, the user can intermix in 
a single file functions compiled normally, functions compiled normally with 
linked calls, and block compiled functions. 
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Blockcompile 



blockcoinpile[blliname;blkfns;entries;flg] blkfns is a list of the functions 

comprising the block, blkname is the name of the 
block* entries a list of entries to the block, 
e.g., 

-BLOCKCOMPILE(SUBPRBLOCK (SUBPAXR SU6LIS SUBPR) (SUBPAIR SUBLIS)) 

Each of the entries must also be on blkfns or an 
error is generated, NOT ON BLKFNS. 

If entries is NIL, listCblkname] is used, e.g., 
«-BLOCKCOMPILE(COUNT (COUNT COUNTl}) 

If blkfns is NIL, listCblkname] is used, e.g., 
«-BLOCKCOMPILE(EQUAL) 

blockcompile asks the standard compiler questions 
and then begins compiling. As with compile , if 
the compiled code is being written to a file, the 
file is closed unless flggT. The value of 
blockcompile is a list of the entries, or if 
entries aNIL. the value is blkname . 



The output of a call to blockcompile is one 
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If only one entry is specified, the block name can also be one of the 
blkfns , e.g. BLOCKCOMPILE(FOO (FOO FIE FUM) (FOO)). However, if more than 
one entry is specified, an error will be generated, 
CAN'T BE BOTH AN ENTRY AND THE BLOCK NAME. 
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function definition for blkname . plus definitions 
for each of the functions on entries if any. 
These entry functions are very short functions 
which immediately call blkname . 

Block Declarations 

Since block compiling a file frequently involves giving the compiler a lot of 
information about the nature and structure of the compilation, e.g., block 
functions, entries, specvars, linking, et al, we have implemented a special 
prettydef command to facilitate this commmunication. The user includes in the 
third argument to prettydef a command of the form 

(BLOCKS block^ ... block2 block^^) where each block^ is a block declaration. 
bcompl and brecompile described below are sensitive to these declarations and 
take the appropriate action. 

The form of a block declaration is: 

(blkname blkfn^ ... blkfng^ (var^ . value) ... (var^ . value)) 

blkfn^ — blkfOj^ are the functions in the block and correspond to blkfns in 
the call to blockcomplle . The (var . value) expressions indicate the settings 
for variables affecting the compilation. 

As an example, the value of editblocks is shown below. It consists of three 
block declarations, editblock , edltflndblock . and edit4e . 
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[RPAOQ EDITBLOCKS 

((EOITBLOCK EOITLO EOITLl UNDOEOITL EOITCOM EDITCOMA EOITCOML 
EDITMAC EDITCOMS EDIT]UN0O UNDOEOITCOM 
UNDOEOITCOMl EOITSMASH EOITNCONC EDITIF E0IT2F 
EOITNTH BPNT BPNTO BPNTl RI RO LI LO BI BO 
EDITDEFAULT ## EDUP EDIT* EOOR EDRPT EOLOC EOLOCL 
EDIT: EOITMBO EOITXTR EOITELT EDITCONT EDITSW 
EDITMV EDITTO EOITBELOW EOITRAN TAILP EOITSAVE 
EDITH (ENTRIES EDITLO ## UNDOEDITL) 
(SPECVARS L COM LCFLG #1 #2 #3 LISPXBUFS 

*«C0MMENT*«FL6 PRETTYFLG UNDOLST 

UNDOLSTl) 
(RETFNS EDITLO) 

(6L0BALVARS EDITCOMSA EDITCOMSL EOITOPS 

HISTORYCOMS EDITRACEFN) 
(BLKAPPLYFNS RI RO LI LO BI BO EDIT: EDITMBD 

EDITMV EDITXTR) 
(BLKLIBRARY LENGTH NTH LAST) 
(NOLINKFNS EDITRACEFN)) 
(EOITFINOBLOCK E0IT4E EDIT4E1 EDITQF EDIT4F EOITFPAT 

EDITFPATl EDIT4F1 EDIT4FZ EDIT4F3 EOITSMASH 
EDITFINDP EOITBF EDITBFl ESUBST 
(ENTRIES EDITQF EDIT4F EDITFPAT EDITFINDP 
EOITBF ESUBST)) 
(E0IT4EBLOCK EDIT4E EDIT4E1 (ENTRIES EDIT4E EDIT4E1] 



Whenever bcompl or brecompile encounter a block declaractlon they reblnd 

retfns , specvars , localfreevars , globalvars , blklibrary , nolinkfns , and linkfns 

to their top level value, bind blkapplyfns and entries to NIL, and bind blkname 

to the first element of the declaration. They then scan the rest of the 

declaration, gathering up all atoms, and setting car of each nonatomic element 

to cdr of the expression if atomic, e.g., (LINKFNS . T), or else to union of 

30 

cdr of the expressions with the current (rebound) value, e.g., 
(GLOBALVARS EDITCOMSA EDITCOMSL). When the declaration is exhausted, the block 
compiler is called and given blkname . the list of block functions, and entries . 



Note that since all compiler variables are rebound for each block declaration. 
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The BLOCKS command outputs a DECLARE expression, which is noticed by bcompl 
and brecompile . 

Expressions of the form (var * form) will cause form to be evaluated and 
the resulting list used as described above, e.g. 
(GLOBALVARS * MYGLOBALVARS ) . 
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the declaration only has to set those variables it wants changed. Furthermore, 
setting a variable in one declaration has no effect on the variable's value for 

another declaration. 

After finishing all blocks, bcoinpl and brecompile treat any functions in the 
file that did not appear in a block declaration in the same way as do tcompl 
and recompile . If the user wishes a function compiled separately as well as in 
a block, or if he wishes to compile some functions (not blockcompile) , with 
some compiler variables changed, he can use a special pseudo-block declaration 
of the form (NIL fn| ... fn^ (var^ . value) ... (var^ . value)) which means 
compile fn^ ... fn^j^ after first setting var^ ... var^ as described above. For 
example, (NIL CGETD FNTYP ARGLIST NARGS NCONCl GENSYH (LINKFNS . T)) 
appearing as a 'block declaration' will cause the six indicated functions to be 
compiled while linkfns »T so that all of their calls will be linked (except for 
those functions on nolinkfns ). 



bcompl 

bcomplC files ;cfile] file s is a list of prettydefed files. (If atomic, 

list[files] is used.) bcompl differs from tcompl 
in that it compiles all of the files at once, 
instead of one at a time. This is to permit one 
block to contain functions in several files. 
Output is to cfile if given, otherwise to a file 

op 

whose name is car[files] suffixed with CON e.g., 
bcompl[(EDIT WEDIT)] produces one file, EDIT. CON. 



Thus if you have several files to be bcompled separately , you must make 
several calls to bcompl . 

See footnote on page 16.11. 
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bcompl asks the standard compiler questions, 
except for OUTPUT FILE: then reads in all of the 
files, adds all nlambda functions in DEFINEQ's to 
nlaroa , nlarol , lambdas to lams , evaluates DECLARE 
expressions,^^ and then processes the block 
declarations as described above. Finally, it 
compiles any functions not mentioned in one of the 
declarations and writes out all other expressions. 

The value of bcompl is the output file. 

Note that it is permissible to tcompl files set up 
bcompl ; the block declarations will simply 
have no effect. Similarly, you can bcompl a file 
that does not contain any block declarations and 
the result will be the same as having tcompl ed it. 



Brecompile 

The purpose of brecompile is to allow the user to update a compiled file 
without requiring an entire bcompl . As with recompile , the usual way to call 
brecompile Involves specifying just its first argument, the symbolic file(s), 
as in the sequence of loading file(s) to PROP, editing selected definitions, 
roakefiling, and then calling brecompile . In this case, brecompile recompiles 
all exprs and works from in-core definitions.^^ Note that this assumes that 



See footnote on page 18.9. 

Note that if any of the functions in a block are recompiled, the entire 
block is recompiled. 
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each symbolic file was produced by makefile , i.e., the arguments to prettydef 
were fileFNS, file, and fileVARS, since brecompile uses fileFNS and file VARS 
to drive its operation. The rest of the discussion below is for various 
nonstandard usages. 

brecorapileC files ;cfile;fns;coreflg] files is a list of symbolic files (if 

atomic, list[ files} is used). cfile is the 
compiled file corresponding to bcompl[ files] or a 
previous brecompile , i.e., it contains compiled 
definitions that may be copied. 

fns is a list of those functions to be recompiled, 
i.e., they have been changed (or defined for the 
first time) since cfile was made. If fnssT, all 
functions defined as exprs (after unbreaking and 
unadvising) are recompiled. 

brecompile asks the standard compiler questions 
except for OUTPUT FILE: As with bcompl , output 
automatically goes to file.COM, where file is the 
first file in files . 

If coreflg «NIL. brecompile proceeds to read in 
each file, collecting all definitions while making 
the appropriate additions to nlama , nlaml , and 
lams , evaluating DECLARE expressions,^^ and 
collecting all block declarations, and other 
expressions which will later be copied to the 
output file. 



See footnote on page 18.9. 
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coreflg sT, brecomplle computes the block 
declarations from the fileVARS for each file in 
files . Similarly, fileFNS and fileVARS are used 
to determine what actually appears on the files. 
The only access to the files is to obtain the date 
for each file so that it can be written onto the 
output file. 

brecompile next processes each block declaration. 
If no functions in the block have been changed, 
the block is copied from cfile as with recompile . 
Otherwise, the entire block is recompiled. For 
pseudo-block declarations of the form 
(NIL fnl ...), all variable assignments are made, 
but only those functions so indicated by fns are 
recompiled. 

As with recompile , the order in which functions 
appear on the file must not be changed unless all 
of the functions that are moved also recompiled. 

After completing the block declarations, 
brecompile processes all functions not appearing 
in a declaration, recompiling only those dictated 
by fns, and copying the compiled definitions of 
the remaining from cfile . 

Finally, brecompile writes the portion of file. CON 



See footnote on page 18.11. 
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corresponding to the non-DEFINEQ expressions. If 
coreflg =NIL; brecomplle simply writes out those 
expressions which it had previously collected. 
Otherwise, it uses fileVARS to determine what is 
on each file and writes the corresponding 
expressions on to the output file. 

The value of brecompile is the output file. 

I*" cfile« NIL, file.COM is used.^^ In addition, if 
fns and coreflg are both NIL, they are set to T. 
This is the standard usage desscribed earlier. 

18.12 Compiler Structure 

The compiler has two principal passes. The first compiles its input 'into a 
macro assembly language called LAP. The second pass expands the LAP code, 
producing (numerical) machine language instructions. The output of the second 
pass is written on a file and/or stored in binary program space. 

Input to the compiler is usually a standard INTERLISP S-expression function 
definition. However, machine language coding can be included within a function 
by the use of one or more assemble forms. In other words, assemble allows the 
user to write protions of a function in LAP. Note that assemble is only a 
compiler directive; it has no independent definition. Therefore, functions 
which use assemble must be compiled in order to run. 



See footnote on page 18.11. 
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18.13 Assemble 



The format of assemble is similar to that of PROG: (ASSEMBLE V Sj $2 . . . S^). 
V is a list of variables to be bound during the first pass of the compilation, 
not during the running of the object code. The assemble statements ... 
are compiled sequentially, each resulting in one or more instructions of object 
code. When run, the value of the assemble 'form' is the contents of ACl at the 
end of the execution of the assemble instructions. Note that assemble may 
appear anywhere in an INTERLISP function. For example, one nay write: 

(IGREATERP (IQUOTIENT (LOC (ASSEMBLE NIL 

(MOVEI 1 , -5) 
(JSYS 13))) 

iOOO) 

4) 

to test if Job runtime exceeds 4 seconds. 

Assemble Statements 

If an assemble statement is an atom, it is treated as a label identifying the 
location of the next statement that will be assembled.'' Such labels defined in 
assemble form are like prog labels in that they may be referenced from the 
current and lower level nested progs or assembles . 

If an assemble statement is not an atom, car of the statement must be an atom 
and one of the following: (1) a number; (2) a LAP op-def (i.e. has a property 
value OPO); (3) an assembler macro (i.e. has a property value AMAC); or (4) one 
of the special assemble instructions given below, e.g. C, CQ, etc. Anything 
else will cause the error message OPCODE? ' ASSEMBLE. 



A label can be the last thing in an assemble form, in which case it labels 
the location of the first instruction after the assemble form. 
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The types of assemble statements are described here in the order of priority 
used in the assemble processor; that is, if an atom has both properties OPD and 
AMAC» the OPO will be used. Similarly a special assemble instruction may be 
redefined via an AMAC. The following descriptions are of the first pass 
processing of assemble statements. The second pass processing is described in 
the section on LAP. page 18.40. 

(1) numbers - If car of an assemble statement is a number, the statement is not 

processed in the first pass. (See page 18.40.) 

(2) LAP op-defs - The property OPD is used for two different types of op-defs: 

PDP-10 machine instructions, and LAP macros. If the OPD 
definition (i.e. the property value) is a number, the op-def is a 
machine instruction. VHien a machine instruction, e.g. HRRZ, 
appears as car of an assemble statement, the statement is not 
processed during the first pass but is passed to LAP. The forms 
and processing of machine instructions by LAP are described on 
page 18.41. 

If the OPD definition is not a number, then the op-def is a LAP 
macro. When a LAP macro is encountered in an assemble statement, 
its arguments are evaluated and processing of the statement with 
evaluated arguments is left for the second pass and LAP. For 
example. LDV is a LAP macro, and (LDV (QUOTE X) SP) in assemble 
code results in (LDV X N) in the LAP code, where N is the value 
of SP. 

The form and processing of LAP macros are described on page 
18.43. 
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(3) assemble macros - If car of an assemble statement has a property AMAC, 
the statement is an assemble macro call. There are two types of 
assemble macros: lambda and substitution. If car of the macro 
definition is the atom LANBOA, the definition will be applied to 
the arguments of the call and the resulting list of statements 
will be assembled. For example, repeat could be a LAMBDA macro 
with two arguments, n and m, which expands into n occurrences of 
ro. e.g. (REPEAT 3 (CARl)) expands to ((CARl) (CAR!) (CAR!)). The 
definition (i.e. value of property AMAC) for repeat is: 

(LAMBDA (N M) 
(PROG (YY) 
A (COND 

((ILESSP N 1) 

(RETURN (CAR YY))) 
(T (SETO YY (TCONC YY M)) 
(SETQ N (SUBl N)) 
(GO A))))) 

If car of the macro definition is not the atom LAMBDA, it must be 
a list of dummy symbols. The arguments of the macro call will be 
substituted for corresponding appearances of the dummy symbols in 
cdr of the definition, and the resulting list of statements will 

op 

be assembled.*"^ For example, ubox could be a substitution macro 
which takes one argument, a number, and expands into instructions 
to compile the unboxed value of this number and put the result on 
the number stack. 



The definition of UBOX is 



((E) 
(CQ (VAG E)) 
(PUSH NP , 1)) 



Note that assemble macros produce a list of statements to be assembled, 
whereas compiler macros produce a single expression. An assemble macro 
which computer a list of statements begins with LAMBDA and may be either 
spread or no-spread. The analogous compiler macro begins with an atom, 
(i.e. is always no-spread) and the LAMBDA is understood. 
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Thus (UBOX (AODl X)) expands to: 



((CQ (VAG (ADDl X))) 
(PUSH NP , 1)) 



(4) special assemble statements - 

(CQ s^ .*.) CQ (compile quote) takes any number of arguments 

which are assumed to be regular S-expressions and 

are compiled in the normal way. E.g. 

(CQ (COND ((NULL Y) (SETQ Y 1))) 
(SETQ X (IPLUS Y Z))) 

Note: to avoid confusion, it is best to have as much of a function as possible 
compiled in the normal way, e.g. to load the value of x to AC 1, (CQ X) is 
preferred to (LOV (QUOTE X) SP). 



(C Sj Sg ...) 



C (compile) takes any number of arguments which 
are first evaluated, then compiled in the usual 
way. Both C and CQ permit the inclusion of 
regular compilation within an assemble form. 



(E ej eg ...) 



E (evaluate) takes any number of arguments which 
are evaluated in sequence. For example, (PSTEP) 
calls a function which increments the compiler 
variable SP. 



(SETQ var) 



Compiles code to set the variable var to the 
contents of ACl. 



(FASTCALL fn) 



Compiles code to call fn. Fn must be one of the 
SUBR's that expects its arguments in the 
accumulators, and not on the push-down stack. 
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Currently, these are cons , and the boxing and 

40 

unboxing routines. 
Example: 

(CQ X) 

(LDV2 (QUOTE Y) SP 2) 
(FASTCALL CONS) 

and consCx,y] will be in ACi. 

(*...) * is used to indicate a comment; the statement is 

ignored. 



COREVALS 

There are several locations in the basic machine code of INTERLISP which may be 
referenced from compiled code. The current value of each location is stored on 
the property list under the property COREVAL.'^^ Since these locations may 
change in different reassemblies of INTERLISP, they are written symbolically on 
compiled code files, i.e. the name of the corresponding COREVAL is written, not 
its value. Some of the COREVALs used frequently in assemble are: 

CONS entry to function CONS 

LIST entry to function LIST 

KT contains (pointer to) atom t 

KNIL contains (pointer to) atom NIL 

MKN routine to box an integer 

MKFN routine to box floating number 

lUNBOX routine to unbox an integer 



list may also be called with fastcall by placing its arguments on the 
pushdown stack, and the number of arguments in ACI. 

The value of corevals is a list of all atoms with COREVAL properties. 
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FUNBOX routine to unbox floating number 



The index registers used for the push-down stack pointers are also included as 
COREVALS. These are not expected to change » and are not stored symbolically on 
compiled code files; however, they should be referenced symbolically in 
assemble code. They are: 

PP parameter stack 

CP control stack 

NP number stack 

18.14 LAP 

LAP (for LISP assembly Processor) expands the output of the first pass of 
compilation to produce numerical machine instructions. 

LAP Statements 

If a LAP statement is an atom, it is treated as a label identifying the 
location of the next statement to be processed. If a LAP statement is not an 
atom, car of it must be an atom and one of the following: (1) a number; (2) a 
machine instruction; or (3) a LAP macro. 

(1) numbers - If car of a LAP statement is a number, a location containing the 
number is produced in the object code. 

e.g. (ADO 1 , A (1)) 

• 

A (i) 

(4) 
(9) 
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statements of this type are processed like machine instructions, 
with the initial number serving as a 36-bit op-code. 

(2) Machine Instructions - If car of a LAP statement has a numeric value for 
the property OPO,^^ the statement is a machine instruction. The 
general form of a machine instruction is: 

(opcode ac • 9 address (index)) 

Opcode is any POP- 10 instruction mnemonic or INTERLISP UUO.^^ 

Ac. the accumulator field, is optional. However, if present, it 
must be followed by a comma. Ac is either a number or an atom 
with a COREVAL property. The low order 4 bits of the number or 
COREVAL are OR'd to the AC field of the instruction. 



@ may be used anywhere in the instruction to specify indirect 
addressing (bit 13 set in the instruction) e.g. (HRRZ 1 , 9 ' V). 

Address is the address field which may be any of the following: 

8 constant Reference to an unboxed constant. A location 
containing the unboxed constant will be created in 
a region at the end of the function, and the 
address of the location containing the constant is 



42 

The value is an 18 bit quantity (rather than 9), since some UUO's also use 
the AC field of the instruction. 

The TENEX JSYS's are not defined, that is, one must write (JSYS 107) 
Instead of (KFORK). 
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placed in the address field of the current 
instruction. The constant may be a number e.g. 
(CAME 1 , « 3596); an atom with a property COREVAL 
(in which case the constant is the value of the 
property, at LOAD time); any other atom which is 
treated as a label (the constant is then the 
address of the labeled location) e.g. 
(MOVE 1 , » TABLE) is equivalent to 

(MOVE I 1 , TABLE); or an expression whose value is 
a number. 

' pointer The address is a reference to a INTERLISP pointer, 
e.g. a list, number, string, etc. A location 
containing the pointer is assembled at the end of 
the function, and the current instruction will 
have the address of this location. E.g. 
(HRRZ 1 , • "IS NOT DEFINED") 
(HRRZ 1 , * (NOT FOUND)) 

* Specifies the current location in the compiled 

function; e.g. (JRST * 2) has the same effect as 
(SKIPA). 



literal atom If the atom has a property COREVAL, it is a 
reference to a system location, e.g. 
(SKIPA 1 , KNIL), and the address used is the 
value of the coreval . Otherwise the atom is a 
label referencing a location in the LAP code, e.g. 
(JRST A). 

number The number is the address; e.g. 
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(MOVSI 1 , 400000Q) 
(HLRZ 2 . 1 (D) 



list The form is evaluated, and its value is the 

address . 

Anything else in the address field causes an error message, e.g. 
(SKIPA 1 , KNILL) - LAPERROR. A number may follow the address 
field and will be added to it, e.g. (JRST A 2). 

Index is denoted by a list following the address field, i.e. the 
address field must be present if an index field is to be used. 
The index (car of the list) roust be either a number, or an atom 
with a property COREVAL, e.g. (HRRZ 1 , 0 (1)) or (ANDM 1 , - 
1 (NP)) 

(3) LAP macros - If car of a LAP statement is the name of a LAP macro, i.e. 

has the property OPO, the statement is a macro call. The 
arguments of the call follow the macro name: e.g. (LQ2 FIE 3). 

LAP macro calls comprise most of the output of the first pass of 
the compiler, and may also be used in assemble . The definitions 
of these macros are stored on the property list under the 
property OPO, and like assembler macros, may be either lambda or 
substitution macros. In the first case, the macro definition is 
applied to the arguments of the call;^^ in the second case, the 
arguments of the call are substituted for occurrences of the 



The arguments were already evaluated in the first pass, see page 16.36. 
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dummy symbols in the definition. In both cases, the resulting 
list of statements is again processed, with macro expansion 
continuing till the level of machine instructions is reached. 

Some examples of LAP macros are shown in Figure 16-2. 
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(DEFLIST(QUOTE( 
(SVN ((N P) 

(MOVE 1 , • N) 
(MRLM 1 , P (PP)))) 
(SVB ((N) 

(HRL I , • N) 
(PUSH PP . 1))) 
(LO ((X) 

(HRRZ 1 , • X))) 
(LQ2 ((X AC) 

(HRRZ AC , • X))) 
(LDV ((A SP) 

(HRRZ 1 . (VREF A SP)))) 
(STV ((A SP) 

(HRRM 1 , (VREF A SP)))) 
(LDV2 ((A SP AC) 

(HRRZ AC , (VREF A SP)))) 
(LOF ((A SP) 

(HRRZ 1 , (FREE A SP)))) 
(STF ((A SP) 

(HRRM 1 , (FREE A SP)))) 
(L0F2 ((A SP) 

(HRRZ 2 . (FREF A SP)))) 
(CARl (NIL 

(HRRZ 1 . 0 (1)))) 
(CDRl (NIL 

(HLRZ 1 , 0 (1)))) 
(CARO ((V) 

(HRRZ 1,0' V))) 
(CAR02 ((V AC) 

(HRRZ AC , e ' V))) 
(CAR2 ((AC) 

(HRRZ AC , 0 (AC)))) 
(RPQ ((V) 

(HRRM 1 . 0 • V) 
(CLL ((NAM N) 

(CCALL N . • NAM))) 
(LCLL ((NAM N) 

(LNCALL N , (MKLCL NAM)))) 
(STE ((TY) 

(PSTEl TY))) 
(STN ((TY) 

(PSTNl TY))) 
(RET (NIL 

(POPJ CP , ) 
(PUSHP (NIL (PUSH PP , 1))) 
(PUSHQ ((X) 

(PUSH PP , • X))) 
))(0UOTE OPD)) 



« STORE VARIABLE NAME) 

* STORE VARIABLE NAME AND VALUE) 

* LOAD QUOTE TO ACl) 
« LOAD QUOTE TO AC) 

* LOAD LOCAL VARIABLE TO ACl) 

* SET LOCAL VARIABLE FROM ACl) 

* LOAD LOCAL VARIABLE TO AC) 

* LOAD FREE VARIABLE TO ACl) 
« SET FREE VARIABLE FROM ACl) 
« LOAD FREE VARIABLE TO AC) 

« CAR OF ACl TO ACl) 

« CDR OF ACl TO ACl) 

« CAR QUOTE) 

« CAR QUOTE TO AC) 

« CAR OF AC TO AC) 

« RPLACA QUOTE) 

« CALL FN WITH N ARCS GIVEN) 

« LINKED CALL WITH N ARGS) 

« SKIP IF TYPE EQUAL) 

« SKIP IF TYPE NOT EQUAL) 

« RETURN FROM FN) 

* PUSH QUOTE) 



Figure 18-2 
Examples of LAP Macros 
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18.15 Using Assemble 

In order to use assemble , it is helpful to know the following things about how 
compiled code is run. All variable bindings and temporary values are stored on 
the parameter pushdown stack. When a compiled function is entered, the 
parameter pushdown list contains, in ascending order of address: 

1. bindings of arguments to the function, where each binding occupies one 
word on the stack with the variable name in the left half and the 
value in the right half. 

2. pointers, to the most recent bindings of free variables used in the 
function. 

The parameter push-down list pointer, index register PP, points to the last 
free variable pointer on the stack. 

Temporary values, PROG and LAMBDA bindings, and the arguments to functions 
about to be called, are pushed on the stack following the free variable 
pointers. The compiler uses the value of the variable SP to keep track of the 
number of stack positions in use beyond the last free variable pointer, so that 
it knows where to find the arguments and free variable pointers. The function 
PSTEP adds 1 to SP, and PSTEPN(N) adds N to SP (N can be positive or negative). 

The parameter stack should only be used for storing pointers. In addition, 
anything in the left half of a word on the stack is assumed to be a variable 
name (see Section 12). To store unboxed numbers, use the number stack, NP. 
Numbers may be PUSH*ed and POP'ed on the number stack. 
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18.16 Miscellaneous 

The value of a function is always returned in ACl. Therefore, the pseudo- 
function» ac, is available for obtaining the current contents of ACl. For 
example (CQ (FOO (AC))) compiles a call to FOO with the current contents of ACl 
as argument, and is equivalent to: 



In using ac, be sure that it appears as the first argument to be evaluated in 
the expression. For example: (CQ (IPLUS (LOC (AC)) 2)) 



There are several ways to reference the values of variables in assemble code. 
For example: 



(PUSHP) 

(E (PSTEP)) 

(CLL (QUOTE FOO) 1) 

(E (PSTEPN -1)) 



ft 



ft 



to put value of X in ACl: 



(CQ X) 



to put value of X in AC3: 



(L0V2 (QUOTE X) SP 3) 



to set X to contents of ACl: 



(SETQ X) 



to set X to contents of AC2: 



(E (STORIN (LIST (QUOTE HRRM) 2 (QUOTE ,) 
(LIST (VARCOMP (QUOTE X)) 
(QUOTE X) 
SP)))) 



to box and unbox a number: 



(CQ (LOC (AC))) 
(FASTCALL MKN) 
(FASTCALL MKFN) 
(CQ (VAG X)) 



box contents of ACl 
box contents of ACl 
floating box contents of ACl 
unboxed value of X to ACl 
unbox contents of ACl 
floating unbox of ACl 



(FASTCALL lUNBOX) 
(FASTCALL FUNBOX) 
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To call a function directly, the arguments must be pushed on the parameter 
stack, and SP must be updated, and then the function called: e.g. 



(CO (CAR X)) 

(PUSHP) (* stack first argument) 

(E (PSTEP)) 
(PUSHQ 3.14) 

(E (PSTEP)) (* stack second argument) 

(CLL (QUOTE FUM) 2) (* call FUH with 2 arguments) 

(E (PSTEPN -2)) (* adjust stack count) 

and is equivalent to: 

(CQ (FUN (CAR X) 3.14)) 

18.17 Compiler Printout and Error Messages 

For each function compiled, whether from tcompl , recompile , or compile , the 
compiler prints: 

(fn COMPILING) 

(fn (arg^ ... arg^) (free| ... free^^)) 

The first message is printed when the compilation of fn begins. The second 
message is printed at the beginning of the second pass of the compilation of 
fn . (arg^ ... arg^^) is the list of arguments to fn., and (free^ ... free^^) the 
list of free variables referenced or set in fn.^^ The appearance of non- 
variables, e.g. function names, words from a comment, etc. in (free^ ... free^^) 
is a good indication of parenthesis errors. 

If the compilation of fn causes the generation of one or more gensym functions 
(see page 18.16), compiler messages will be printed for these functions between 
the first message and the second message for fn, e.g. 



Does not include variables on globalvars . see page 18.6. 
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(FOO COMPILING) 
(FOOA0027 COMPILING) 
(FOOA0027 NIL (X)) 
(FOO (X) NIL) 

The compiler output for block conpllation is similar to normal compilation. 
The pass one message, i.e. (fn compiling) is printed for each /unction in the 
block. Then a second pass message is printed for the entire block. Then both 
messages are printed for each eiitri^ to the block. 

In addition to the above output, both recompile and brecompile print the name 
of each function that is being copied from the old compiled file to the new 
compiled file. The normal compiler messages are printed for each function that 
is actually compiled. 

Compiler Error Messages 

Messages describing errors in the function being compiled are also printed on 
the teletype. These messages are always preceded by Unless otherwise 

indicated below, the compilation will continue. 

((form) - NON ATOMIC CAR OF FORM) 

If user intended to treat the value of form as a function, he should 
apply* ' form is compiled as if apply" had been used. See Section 

8. 

(fn - NO LONGER INTERPRETED AS FUNCTIONAL ARGUMENT) 

The compiler has assumed fn is the name of a function. If the user 



The names of the arguments to the block are generated by suffixing and 
a number to the block name, e.g. 

(FOOBLOCK (FOOBLOCi;#0 F00BL0CIC#1) free-variables). 
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intended to treat the mlue of fn as a function, he must use apply* 
See Section 8.^^ 



(tg - MULTIPLY DEFINED TAG) 

tfl is a PROG label that is defined nore than once in a single PROG. 
The second definition is ignored. 

(tg - UNDEFINED TAG) 

t£ is a PROG label that is referenced but not defined in a PROG. 

(tg - MULTIPLY DEFINED TAG, ASSEMBLE) 

tfl is a label that is defined more than once in an assemble form. 

(tg - UNDEFINED TAG, ASSEMBLE) 

tfl is a label that is referenced but not defined in an ASSEMBLE form. 

(tg - MULTIPLY DEFINED TAG, LAP) 

tg is a label that was encountered twice during the second pass of the 
compilation. If this error occurs with no indication of a multiply 
defined tag during pass one, the tag is in a LAP macro. 

(tg - UNDEFINED TAG, LAP) 

tg is a label that is referenced during the second pass of compilation 
and is not defined. LAP treats t£ as though it were a coreval . and 
continues the compilation. 
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This message is printed when fn is not defined, and is also a local 
variable of the function being compiled. Note that earlier versions of the 
INTERLISP compiler did treat fn as a functional argument, and compiled code 
to evaluate it. 
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(fn - USED AS ARG TO NUMBER FN?) 

The value of a predicate, such as GREATERP or EQ, is used as an 
argument to a function that expects numbers, such as IPLUS. 

(x - IS GLOBAL) 

X is on fllobalvars . and is also rebound in the function being 
compiled, either as an argument or as a local variable. The error 
message is to alert the user to the fact that other functions will not 
see this binding, since x is always accessed directly through its 
value cell. 

(op - OPCODE? - ASSEMBLE) 

oe> appears as car of an assemble statement, and is illegal. See page 
16.35-39 for legal assemble statements. 

(blknaroe - USED BLKAPPLY WHEN NOT APPLICABLE) 

blkapply is used in the block blkname , but there are no blkapplyfns or 
entries declared for the block. 

(fn - ILLEGAL RETURN) 

return encountered when not in prog . 

(tg - ILLEGAL GO) 

go encountered when not in a prog . 

(fn NOT COMPILEABLE) 

An expr definition for fn could not be found. In this case, no code 
is produced for fn, and the compiler proceeds to the next function to 
be compiled, if any. 

fn NOT COMPILEABLE. 
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Same as above except generates an error, thereby aborting all 
compilation. For example, this error condition occurs if fn is one of 
the functions in a blocli. 

fn NOT FOUND. 

Occurs when recompile or brecompile try to copy the compiled 
definition of fn from cfile, and cannot find it. See page 16.12. 
Generates an error. 

fn NOT ON BLKFNS. 

fn was specified as an entry to a block, or else was on blkapplyfns . 
but did not appear on the blkfns . Generates an error. 

fn CAN'T BE BOTH AN ENTRY AND THE BLOCK NAME. 
Generates an error. 



(fn NOT IN FILE - USING DEFINITION IN CORE) 
on calls to bcompl and brecompile . 
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SECTION 19 
ADVISING 



The operation of advising gives the user a way of modifying a function without 
necessarily knowing how the function works or even what it does. Advising 
consists of modifying the interface between functions as opposed to modifying 
the function definition itself* as in editing, break , trace , and breakdown , 
are examples of the use of this technique: they each modify user functions by 
placing relevant computations between the function and the rest of the 
programming environment. 

The principal advantage of advising, aside from its convenience, is that it 
allows the user to treat functions, his or someone else's, as "black boxes," 
and to modify them without concern for their contents or details of operations. 
For example, the user could modify sysout to set sysdate to the time and date 
of creation by advise[SYSOUT;(SETQ SYSDATE (DATE))] 

As with break , advising works equally well on compiled and interpreted 
functions. Similarly, it is possible to effect a modification which only 
operates when a function is called from some other specified function, i.e., to 
modify the interface between two particular functions, instead of the interface 
between one function and the rest of the world. This latter feature is 
especially useful for changing the internal workings of a system function. 



Advising was developed and implemented by W. Teitelman. 
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For example, suppose the user wanted time (Section 21) to print the results of 
his measurements to the file FOO instead of the teletype. He could accomplish 
this by A0VISE(((PRIN1 PRINT SPACES) IN TIME) BEFORE (SETQQ U FOO)) 

Note that advising print , print , or spaces directly would have affected all 
calls to these very frequently used function. whereas advising 
((PRINl PRINT SPACES) IN TIME) affects Just those calls to prinl . print , and 
spaces from time . 

Advice can also be specified to operate after a function has been evaluated. 
The value of the body of the original function can be obtained from the 
variable lvalue , as with break!,. For example, suppose the user wanted to 
perform some computation following each sysin . e.g. check whether his files 
were up to date. He could then: 

ADVISE(SYSOUT AFTER (COND ((LISTP fVALUE) — )))^ 
19.1 Implementation of Advising 

The structure of a function after it has been modified several times by advise 
is given in the following diagram: 



After the sysin , the system will be as it was when the sysout was 
performed, hence the advice must be to sysout . not sysin . See Section 14 
for complete discussion of sysout /sysin . 
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FIGURE 19-1 
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The corresponding INTERLISP definition is: 



(LAMBDA arguments (PROG (! VALUE) 
(SETQ ! VALUE (PROG NIL 
advice 1 



advicen 

(RETURN form))) 
advicel 



ADVICE 
BEFORE 



ADVICE 
AFTER 

adviceiii 

(RETURN iVALUE))) 
where form is equivalent to the original definition. 

Note that the structure of a function modified by advise allows a piece of 
advice to bypass the original definition by using the function RETURN. For 
example, if (COND ((ATOM X) (RETURN Y))) were one of the pieces of advice 
BEFORE a function* and this function was entered with x atomic, £ would be 
returned as the value of the inner PROG, lvalue would be set to j^, and control 
passed to the advice, if any, to be executed AFTER the function. If this same 
piece of advice appeared AFTER the function, ^ would be returned as the value 
of the entire advised function. 

The advice (COND ((ATOM X) (SETQ i VALUE Y))) AFTER the function would have a 
similar effect, but the rest of the advice AFTER the function would still be 
executed. 



Actually, advise uses its ovm versions of PROG, SETQ, and RETURN, (called 
ADV-PROG, ADV-SETQ, and ADV-RETURN) in order to enable advising these 
functions. 
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If fn was originally an EXPR, form is the body of the definition, otherwise 
a form using a gensym which is defined with the original definition. 
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19.2 Advise Functions 



Advise 

Advise is a function of four arguments: fn, when , where , and what . f_n is the 
function to be modified by advising, what is the modification, or piece of 
advice, when is either BEFORE or AFTER, and indicates whether the advice is to 
operate BEFORE or AFTER the body of the function definition is evaluated. 
where specifies exactly where in the list of advice the new advice is to be 
placed, e.g., FIRST, or (BEFORE PRINT) meaning before the advice containing 
print , or (AFTER 3) meaning after the third piece of advice, or even (: TTY:). 
If where is specified, advise first checks to see if it is one of LAST, BOTTOM, 
END, FIRST, or TOP, and operates accordingly. Otherwise, it constructs an 
appropriate edit command and calls the editor to insert the advice at the 
corresponding location. 

Both when and where are optional arguments, in the sense that they can be 
omitted in the call to advise . In other words, advise can be thought of as a 
function of two arguments [fn;what], or a function of three arguments: 
Cfn;when;what], or a function of four arguments: [fn;when;where;what]. Note 
that the advice is always the last argument. If when sNIL. BEFORE is used. If 
where =NIL, LAST is used. 

advise[fn;when;where;what] fn is the function to be advised, when g BEFORE or 

AFTER, where specifies where in the advice list 
the advice is to be inserted, and what is the 
piece of advice. 

If fn is of the form (fnl IN fnZ), fnl is changed 
fnl-IN-fn2 throughout fn2, as with break, and 
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then fnl-IN-fnZ is used in place of fn. 



If fn is broken, it is unbroken before advising. 

If fn is not defined, an error is generated, 
NOT A FUNCTION. 

If fn is being advised for the first time, i.e. if 
getp[ name, ADVISED }-N XL, a gensym is generated and 
stored on the property list of fn under the 
property ADVISED, and the gensym is defined with 

the original definition of fn. An appropriate S- 

ft 

expression definition is then created for fn. 
Finally, fn is added to the (front of) 
advisedfns . 

If fn has been advised before, it is moved to the 
front of advisedfns . 

The advice is inserted in fn*s definition either 
BEFORE or AFTER the original body function 
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If fnl and/or fnZ are lists, they are distributed as shown in the example 
on page 19.2. 

Using private versions of PROG, SETQ, and RETURN, so that these functions 
can also be advised. 



So that unadvise[T] always unadvises the last function advised. See page 
19.8. 
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depending on when. Within that context, its 
position is determined by where. If where «LAST, 
BOTTON, END, or NIL, the advice is added following 
all other advice, if any. If whejre»FIRST or TOP. 
the advice is inserted as the first piece of 
advice. Otherwise, where is treated as a command 
for the editor, a la breajcin, e.g. (BEFORE 3), 
(AFTER PRINT) . 

Finally list[when;where;what] is added (by 
addprop ) to the value of property ADVICE on the 
property list fn. Note that this property value 
is a list of the advice in order of calls to 
advise , not necessarily in order of appearance of 
the advice in the definition of fn. 

The value of advise is fn. 

If fn is non-atomic, every function in fn is 
advised with the same values (but copies) for 
when , where , and what . In this case, the value of 
advise is a list of individual functions. 

Note: advised functions can be broken. (However if a function is broken at 
the time it is advised, it is first unbroken.) Similarly, advised functions can 
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A special case is whensBIND. Here the advice is treated as a list of PROG 
variables to be bound. The variables are nconced to the PROG variable list 
containing lvalue . See page 19.4. 

So that a record of all the changes is available for subsequent use in 
readvising, see page 19.8. 



19.7 



be edited, including their advice, unadvise will still restore the function to 
its unadvised state, but any changes to the body of the definition will 
survive. Since the advice stored on the property list is the same structure as 
the advice inserted in the function, editing of advice can be performed on 
either the function's definition or its property list. 

unadviseCx] is a no-spread NLANBDA a la unbreak . It takes an 

indefinite number of functions and restores them 
to their original unadvised state, including 
removing the properties added by advise . 
unadvise saves on the list advin foist enough 
information to allow restoring a function to its 
advised state using readvise . advinfolst and 
readvise thus correspond to br kin foist and 
rebreak . 



unadvise[] unadvises all functions on 
advlsedfns .^*^ It first sets advinfolst to NIL. 

unadvise[T] unadvises the first function of 
advisedfns, i.e., the most recently advised 
function. 



readvise[x] is a no-spread NLANBDA a la rebreak for restoring 

a function to its advised state without having to 
specify all the advise information. For each 
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Except if a function also contains the property READVICE (see readvise 
below), unadvise moves the current value of the property ADVICE to 
READVICE. 

In reverse order, so that the most recently advised function is unadvised 
last . 
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function on x, readvise retrieves the advise 
information either from the property READVICE for 
that function, or from advinfblst , and performs 
the corresponding advise operation(s) . In 
addition it stores this information on the 
property READVICE if not already there. If no 
information is found for a particular function* 
value is (fn - NO ADVICE SAVED). 

readvise[] readvises everything on advinfolst . 

readvise[T] readvises Just the first function on 
advinfolst . i.e., the function most recently 
unadvised. 

The difference between advise , unadvlse, and readvise versus break , unbreak , 
and rebreak , is that if a function is not rebroken between successive 
unbreak[]*s, its break information is forgotten. However, once readvised , a 
function's advice is permanently saved on its property list (under READVICE); 
subsequent calls to unadvlse will not remove it. In fact, calls to unadvlse 
update the property READVICE with the current value of the property ADVICE, so 
that the sequence readvise , advise , unadvlse causes the augmented advice to 
become permanent. Note that the sequence readvise, advise , readvise removes 
the 'intermediate advice' by restoring the function to its earlier state. 

advisedurop[x;f Ig] Used by prettydef when given a command of the form 

(ADVISE --) or (ADVICE --). flg =T corresponds to 
(ADVISE --), i.e. advlsedump writes both a def list 
* readvise . flgsNIL corresponds to (ADVICE — 
), i.e. only the deflist is written. In either 
case, advlsedump copies the advise Information to 



19.9 



tho property READVICE, thereby making it 
'permanent* as described above. 
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advising 19.1-10 

AFTER (as argument to advise) 19.2,4-6 

BEFORE (as argument to advise) 19.4-6 

BIND (as argument to advise) 19.7 

BOTTOM (as argument to advise) 19.5,7 

FIRST (as argument to advise) 19.5,7 

(fnl IN fn2) 19.5 

fnl-IN-fnZ 19.5 

GENSYM[CHAR] 19.4.6 

LAST (as argument to advise) 19.5,7 

NOT A FUNCTION (error message) 19.6 

PRETTYDEF ... 19.9 

READVICE (property name) 19.8-10 

READVISECX] NL« 19.8-9 

TOP (as argument to advise) 19.5,7 

UNADVISEtX] NL« 19.6,8-9 

UNBROKEN (typed by advise) 19.6 

IVALUE (with advising) 19,2.4 
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SECTION 20 
PRINT5TRUCTURE AND INTERSCOPE 



20 . 1 Prints tructure 



In trying to work with large programs, a user can lose track of the hierarchy 
which defines his program structure; it is often convenient to have a map to 
show which functions are called by each of the functions in a system. If fn is 
the name of the top level function called in your system, then typing in 
printstructure[ fn] will cause a tree printout of the function-call structure of 
fn. To illustrate this in more detail, we use the printstructure program 
itself as an example. 



A preliminary version of printstructure was written by D. G. Bobrow. The 
current form of printstructure was written by W. Teitelman. 
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PRINTSTRUCTURE PRGETD 

PROGSTRUC PRGETD 

PRGSTRC NOTFN PRGETD 
PROGSTRUC 
PRGSTRCl PRNCONC 
PRGSTRCl 
PRGSTRC 

PRNCONC 
PRGSTRC 
CALLSl MAKELIST 
NOTFN 

CALLS2 CALLSl 
PRGETD 

TREEPRINT TREEPRINTl 

TREEPRINT 
VARPRINT VARPRINTl TREEPRINTl 

VARPRINT2 ALLCALLS ALLCALLSl ALLCALLSl 

TREEPRINTl 

PRINTSTRUCTURE [X.FILE: DONELST.N,TREELST.TREEFNS,LSTEM,X, Y.Z, 
FN , TREE , PRDEPTH, LAST-PRINTSTRUCTURE] 
CALLED BY: 

PRGETD [X.FLG; ; ] 

CALLED BY: PRINTSTRUCTURE, PROGSTRUC, NOTFN, CALLSZ 

PROGSTRUC [FN.DEF; N. Y.Z,CALLSFLG,VARSFLG.VARS1.VARS2.D,X; N,D0NELST3 
CALLED BY: PRINSTRUCTURE, PRGSTRC 

PRGSTRC [X,HEAD,FLG; Y,TEM,X; VARSFLG,0,NOFNS,CALLSFLG,N,DONELST. 
TREEFNS.N0TRACEFNS,FN,VARS1,QU0TEFNS3 
CALLED BY: PROGSTRUC. PRGSTRC 1 , PRGSTRC 

NOTFN [FN; DEF; NOFNS, YESFNS,FIRSTLOC,LASTLOC] 
CALLED BY: PRGSTRC, CALLSl 

PRGSTRCl [L,HEAD,FLG; A.B; VARS1,VARS2] 
CALLED BY: PRGSTRC. PRGSTRCl 

PRNCONC [X,Y; ; CALLSFLG] 

CALLED BY: PRGSTRCl .PRGSTRC 

CALLSl [ADR.GENFLG.D; LIT.END,V1,V2,LEFT,0PD,X,X; VARSl,VARS2, 
VARSFLG] 

CALLED BY: PROGSTRUC. CALLS2 

MAKELIST [N.ADR; L; ] 
CALLED BY: CALLSl 



Figure 20-1 
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The upper portion of this printout is the usual horizontal version of a tree. 
This tree is straighforwardly derived from the definitions of the functions: 
printstructure calls prgetd, progstruc , treeprint , and varprlnt , progstruc in 
turn calls prgetd , prgstrc and callsl . prgstrc calls notfn, progstruc , 
prgstrcl , prnconc , and itself, prgstrcl calls prnconc , itself, and prgstrc . 
Note that a function whose substructure has already been shown is not expanded 
in its second occurrence in the tree. 

The lower portion of the printout contains, for each function, information 
about the variables it uses, and a list of the functions that call it. For 
example, printstructure is a function of. two arguments, x and file . It binds 
eleven variables internally: donelst , n, ... tree ,^ and uses prdepth and 
last -printstructure as free variables. It is not called by any of the 
functions in the tree, prgetd is a function of two arguments, x and fig , binds 
no variables internally, uses no free variables, and is called by 
printstructure . progstruc , notfn and calls2 . 

printstructure calls many other low-level functions such as getd , car , list , 
nconc , etc. in addition to the four functions appearing in the above output. 
The reason these do not appear in the output is that they were defined 
"uninteresting" by the user for the purposes of his analysis. Two functions, 
f irstfn and lastfn , and two variables, yesfns and nofns are used for this 
purpose. Any function that appears on the list nofns is not of interest, any 
function appearing on yesfns is of interest. 

yesfns =T effectively puts all functions on yesfns . As for functions appearing 
on neither nofns or yesfns , all interpreted functions are deemed interesting, 
but only those compiled functions whose code lies in that portion of bpspace 



Variables are bound internally by either PROGs LAMBOA-expressions . 
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between the two limits established by f irstfn and lastfn . For example, the 
above analysis was performed following firstfn[PRINTSTRUCTURE] and 
lastfnCALLCALLSl]. 

Three other variables, notracefns , quotefns , and prdepth also affect the action 
of printstructure . Functions that appear on the list notracefns will appear in 
the tree, assuming they are "interesting" functions as defined above, but their 
definitions will not be analyzed. 

Functions that appear on quotefns are analyzed, assuming they are 
"interesting," but when they appear as car of a form, the rest of the form, 
i.e., the arguments, is not analyzed. For example, if the function prinq were 
defined as (NLAMBDA (X) (MAPC X (FUNCTION PRINl))) and included on quotefns , 
and the form (PRINQ (NOW IS THE TINE)) appeared in a function being analyzed, 
prinq would appear in the tree and be analyzed but the 'form' (NOW IS THE TIME) 
would be skipped. The initial setting of quotefns is NLAMBDAs, which 
effectively includes all NLAMBDAs (functions with argtype 1 or 3) on quotefns , 
except for those functions which printstructure knows require evaluation, e.g., 
ersetq , nlsetq , or , and, etc. The arguments to these functions are always 
analyzed. 

Finally, prdepth is a cutoff depth for analysis. It is initially set to 7. 

printstructure has incorporated in it the necessary information for analyzing 
non-standard forms such as cond , prog and selectq . It is also capable of 
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analyzing compiled or interpreted functions equally well. In the case of 
compiled functions, prlntstructure will automatically analyze any functions 
generated by the compiler, such as those caused by compiling forms beginning 
with ersetq , nlsetq , or function . 

If prlntstructure encounters a form beginning with two left parentheses in the 
course of analyzing an interpreted function (other than a CONO clause or open 
lambda expression) it notes the presence of a possible garentheses error by the 
abbreviation P.P.E., followed by the function in which the form appears, and 
the form itself, as in the example below. Note also that since prlntstructure 
detects functions that are not defined, (i.e., atoms appearing as CAR of a 
form), prlntstructure is a useful tool for debugging. 



except there may be some confusion in analyzing compiled functions, if the 
name of a variable and a function are the same. For this reason, it is 
best to prlntstructure the Interpreted version of a function whenever 
possible. 



Prlntstructure knows about CLISP (Section 23) to the extent that if it 
encounters untranslated iterative statements or IF-THEN-ELSE statements, it 
will automatically dwlmlfy them before analyzing them. 
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*-PP FOO 

(FOO 

[LAMBDA (X) 
(COND 

((CAR X) (FOOl X)) 
(T ((CONS X (CAR X]) 

FOO 

•-PRINTSTRUCTURE(FOO) 
FOO FOOl 

FOO [X; ; ] 

CALLED BY: 

FOOl IS NOT DEFINED. 

P.P.E. IN FOO - ((CONS X (CAR X))) 

Figure 20-2 

Other Options 

printstructure is a function of three arguments, x, exprf Ig , and file . 
printstructure analyzes x, sets the free variable last- print structure to the 
results of its analysis, prints the result (in the format shown earlier) to 
file (which is opened if necessary and closed afterwards), and returns x as its 
value. Thus if the user did not want to see any output, he could call 
printstructure with file sNIL;.^ and then process the result himself by using 
last-printstructure . 

printstructure always checks for EXPR properties on the property list of 
functions that are not defined. However, if exprflg sT. printstructure will 
prefer to analyze EXPR definitions whenever possible, i.e. if the function 



NIL: is a TENEX output device that acts like a 'bottomless pit*. Note 
that f ile =NIL (not NIL:) means print the tree to primary output file. 
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definition call contains a compiled definition, and there is also an EXPR 
property* the latter will be analyzed. See footnote on page 20.5. 



X can bo NIL, a list, a function, or an atom that evaluates to a list. If x is 
NIL, printstructure does not perform any analysis, but simply prints the result 
of the last analysis, i.e., that stored on last-printstructure . Thus the user 
can effectively redirect the output that is going to the terminal to a disc 
file by aborting the printout, and then performing printstructure[NIL;f lie]. 

If X 1& Ei list, printstructure analyzes the first function on x, and then 
analyzes the second function, unless it was already analyzed, then the third, 
etc., producing however many trees required. Thus, if the user wishes to 
analyze a col lection of functions, e.g., breakfns , he can simply perform 
(PRINTSTRUCTURE BREAKFNS). 

If X is not a list, but is the name of a function, printstructure[x] is the 
same as printstructure[ (x) ]. Finally, if the value of x is a list of 
functions, printstructure will process that list as described above. 

Note that in the case that x is a list, or evaluates to a list, subsequent 
functions are not separately analyzed if they have been encountered in the 
analysis of a function appearing earlier on the list. Thus, the ordering of x 
can be important. For example, if both FOO and FIE call FUN, 
printstructure[ (FOO FIE FUM)], will produce a tree for FOO containing embedded 
in it the tree for FUM. FUM will not be expanded in the tree for FIE, nor will 
it have a tree of its own. (Of course, if FOO also calls FIE, then FIE will 
not have a tree either.) The convention of listing FUM can be used to force 
printstructure to give FUM a tree of its own. Thus 
printstructure[ (FOO FIE (FUM))] will produce three trees, and neither of the 
calls to FUM from FOO or FIE will be expanded in their respective trees. Of 
course, in this example, the same effect could have been achieved by 
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reordering, i.e., printstructureC(FUM FOO FIE)]. However, if FOO, FIE, and 
FUM, all called each other, and yet the user wanted to see three separate 
trees, no ordering would suffice. Instead, the user would have to do 
printstructure[((FOO) (FIE) (FUM))]. 

The result of the analysis of printstructure is in two parts: donelst , a list 
summarizing the argument/variable information for each function appearing in 
the tree(s), and treelst, a list of the trees, last-printstructure is set to 
cons[ donelst ;treelst]. 

donelst is a list consisting, in alternation, of the functions appearing in any 
tree, and a variable list for that function, car of the variable list is a 
list of variables bound in the function, and cdr is a list of those variables 
used freely in the function. Thus the form of donelst for the earlier example 
would be: 

(PRINTSTRUCTURE ((X FILE DONELST N TREELST TREEFNS L TEM X Y Z 
FN TREE) PRDEPTH LAST-PRINTSTRUCTURE) PRGETO ((X FLG)) 
PROGSTRUC (( FN DEF N Y Z CALLSFLG VARSFLG VARSl VARS2 0 X) 
N DONELST) ... ALLCALLSl ((FN TR A B))) 

Possible parentheses errors are indicated on donelst by a non-atomic form 
appearing where a function would normally occur, i.e., in an odd position. The 
non-atomic form is followed by the name of the function in which the P.P.E. 
occurred. 
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Printstructure Functions 



printstructure[x;exprflg;file] analyzes x» saves result on 

last-prlntstructure , outputs trees and variable 
information to file , and returns x as its value. 

If exprflg aT, printstructure will prefer to 
analyze expr's. See page 20.6. 

treeprint[x;n] prints a tree in the horizontal fashion shown in 

the examples above, i.e., printstructure performs 
(MAPC TREELST (FUNCTION TREEPRINT)). 

yarprint[donelst ;treelst] prints the "lower half of the printstructure 

output. 

allcalls[fn;treelst] uses treelst to produce a list of the functions 

that call fn. 

firstfn[fn] If fn=T, lower boundary is set to 0, i.e., all 

subrs and all compiled functions will pass this 
test. If fnsNIL, lower boundary set at end of 
bpspace, i.e., no compiled functions will pass 
this test. Otherwise fn is the name of a compiled 
function and the boundary is set at fn, i.e., all 
compiled functions defined earlier than jfn are 
rejected. 

lastfn[fn] if fnsNIL, upper boundary set at end of bpspace, 

i.e., all compiled functions will pass this test. 
Otherwise boundary set at fn, i.e., all compiled 
functions defined later than fn are rejected. 
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Thus to accept all compiled functions, perform firstfn[T] and lastfnCNIL]: to 
reject all compiled functions, perform firstfnC]. 



calls[fn ;exprf lg;varsflg] 



Is a fast •onG-level' 



prlntstructure , i.e., it 



Indicates what functions fn calls, but does not go 
further and analyze any of them, c alls does not 
print a tree, but reports its findings by 
returning as its value a list of three elements: a 
list of all functions called by fn, a list of 
variables bound in fn, and a list of variables 
used freely in fn, e.g., 

callsCprogstruc] » ((PRGETO EXPRP PRGSTRC CCOOEP 
CALLSl ATTACH) (FN DEF N Y Z CALLSFLG VARSFLG 
VARSl VARS2 D X) (N DONELST)) 

fn can be a function name, a definition, or a 
form. Calls first does firstfn(T), lastfn( ) so 
that all subrs and compiled functions appear, 
except those on nofns . If varsf Ig is T, calls 
ignores functions and only looks at the variables 
(and therefore runs much faster). 



vars[fn;exprf Ig] 



cdrCcallsC fn ;6xprf lg;T]] 



freevarsC fn;exprf Ig] 



cadr[ vars[ f n ; expr f Ig ] ] 
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20.2 Int^rscope 



While printstructure is a convenient tool for giving the user an oueruiew of 
the structure of his programs, it is not well suited for determining the answer 
to particular questions the user may have about his programs. For example, if 
FOO uses X freely, and the user wants to know where X is bound 'above' FOO, he 
has to visually trace back up the tree that is output by printstructure , and, 
at each point, look down at the lower portion of the printout and find whether 
the corresponding function binds X. For large systems, such a procedure can be 
quite tedious. Furthermore, printstructure does not even compute certain 
certain important types of information. For example, printstructure does not 
distinguish between functions that use a variable freely and those that set it 
(or smash it). 

I ntersco pe is an extension of printstructure designed to resolve these 
shortcomings. Like printstructure , interscope analyses programs (functions), 
although it extracts considerably more information and relationships than does 
printstructure . However, instead of presenting the Information it obtains in a 
predetermined format, interscope allows the user to ask it questions about the 
programs it has analysed, i.e. to interrogate its data base. These questions 
can be input in English, and contain conjunctions, disjunctions, and negations 
of the many relationships between functions and variables that interscope knows 
about. The questions can be closed questions, e.g. '*DOES FOO CALL FIE?", or 
open questions, "WHAT FUNCTIONS CALL FIE?". The answers to some questions are 
obtainable directly from the data base, e.g. "WHAT VARIABLES DOES FOO SET?" 
Other questions cause interscope to search its data base, e.g. 
"WHAT FUNCTIONS BIND VARIABLES THAT FOO SETS?". Figure 20-3 contains a sample 
session with interscope . 



Interscope was written by P. C. Jackson. 
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•-INTERSCOPE] 

Hello, shall I analyze a system? 
&-WTFIXFNS AND CLISPFNS. 

This may take a few minutes. 



[1] 



GC: 8 

1233, 10431 FREE WORDS 

Shall I analyze another system? 
&*-N0 [2] 

Ok, what would you like to know? 

&WHO CALLS RETDWIM? 

(WTFIX FIX89TYPEIN FIXAPPLY FIXATOM FIXCONTINUE CLISPATOM FIXT) 
&HOW IS CLISPATOM CALLED? 

I didn't understand that. [3] 
&WHAT FUNCTIONS CALL CLISPATOM? [4] 
(WTFIX FIXAPPLY FIXATOM) 
&WHAT FREE VARIABLES DOES CLISPATOM USE? 

(ONLYSPELLFLG CLISPCHANGES CLISPFLG TYPE-IN? CLISPSTATS INFIXSTATS LSI 
FAULTXX CHCONLST FAULTX DWIMIFYFLG 89CHAN6E FAULTPOS) 
&WMO BINDS TAIL? 

(WTFIX RETDWIMl RETDWIM2 RETDWIM3 CLISPFUNCTION? CLISPATOMO CLISPATOMl 

CLISPATOMIA CLISPAT0M2A DWIMIFYIA 0WIMIFY2 DWIMIFY2A CLISPRESPELL) 

&WH0 BINDS TAIL AND CALLS CLISPATOM SOMEHOW? 

(WTFIX DWIMIFY2) 

&WHAT VARS DOES HELPFIX CHANGE? 

(FORM LASTPOS NOCHANGEFLG HELPFIXTAIL FN TEM BRKEXP) 
&WHAT FUNCTIONS CHANGE THE VARIABLE TENTATIVE? 
(CLISPATOMl CLISPAT0M2 CLISPAT0M2C CLISPAT0M2A CLISPATOMIA) 

&WH0 CHANGES TAIL? 

(FIXATOM HELPFIXl CLISPATOMl CLISPAT0M2 DWIMIFY2) 
&WHAT FNS USE TEM AS AN INTERANL VAR AND 
. . .ARE CALLED BY CLISPATOM INDIRECTLY? 
INTERANL=INTERNAL ? Yes 
(RETDWIM RETDWIMl FIX89TYPEIN) 
&HOW DOES CLIAPTOM CALL LISTP? 
CLIAPTOM=CLISPATOM ? Yes 

((CLISPATOM LISTP) (CLISPATOM *«* RETDWIM *«« LISTP) (CLISPATOM [5] 

FIX89 FIX89A LISTP)) 

&SHOW ME THE PATHS FROM CLISPATOM TO LISTP. 
CLISPATOM LISTP 

RETDWIM LISTP [6] 
RETDWIMl LISTP 

FIX89TYPEIN RETDWIM ... 

FIX89 FIX89A LISTP 
&DOES GETVARS SMASH ANY VARIABLES? 
(L) 

&SHOW ME HOW GETVARS SMASHES L. 

(NCONC L (AND (LISTP X) (MAPCAR & &))) 
&GOODBYE. 

Goodbye . 



Figure 20-3 
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In order to answer questions about programs, intcrscope must analyze them and 
build its data-base. When interscope is first called, it will ask the user 
what functions he wants analyzed. The user can respond to this question by 
giving interscope either: 1) the name of the top level function called in his 
system, or 2) the name of a variable that evaluates to a list of top level 
functions, or 3) the list itself. All of the functions below each top level 
function will be analyzed, except those which are declared to be 
"uninteresting," as described below. Note that after interscope goes into 
question-answering mode, the user can instruct interscope to analyze 
additional functions, either in English input, e.g. "ANALYZE FOOFNS." or by 
calling the function lookat directly (page 20.17). 

The structure of interscope may be divided into three major subsystems: a 
top-level monitor function, an English preprocessor, and the functions which 
build and search the data base. The monitor function is implemented via 
userexec (see Section 22), so that the features of the programmer's assistant 

0 

are available from within interscope ." For example, the user can REDO or FIX 
interscope questions, interrogate the history list for his session, or run 



When intorscope is first called, and it has not previously analyzed any 
functions, it is in analysis mode, as indicated by its greeting and prompt 
character (&♦- instead of &) (see [1] in Figure 20-3). Intcrsco pe goes into 
question-answering mode when the user answers NO to the question "Shall I 
analyse a (another) system?" ([2] in Figure 20-3), The only difference 
between analysis mode and question-answering mode is that in analysis mode, 
intorscope treats forms as indicating a list of functions to be analysed, 
whereas in question-answering mode, intcrscope simply passes forms back to 
lispx for evaluation. 



intcrscope assumes that any input line terminated by a punctuation mark is 
intended for it to process, interscope will also attempt to process other 
input lines, i.e. those not ending in punctuation. However, if it is not 
able to make sense of the input, interscope will assume that it was 
intended to be handled by lisp x, and pass it back for evaluation. For 
example, if the user types "HAS THOU SLAIN THE JABBERWOCK?" , interscope 
will respond "I didn't understand that", but if the user omits the '?', the 
line will be given to lispx for evaluation and (probably) cause a 
U.D.F. HAS error. 
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programs from within interscope . 



The English preprocessor translates English questions, statements, and 
commands into INTERLISP forms appropriate for searching and building the 
interscope data base. Although this preprocessor is fairly flexible and 
robust (e.g. includes spelling correction), it translates only a limited subset 
of English sentences, and replies "I didn't understand that." to anything 
outside this subset ([3] in Figure 20-3).^^ When this happens, usually a simple 
rephrasing of the question will suffice to allow interscope to handle it ([4] 
in Figure 20-3), 

The interscope data-base can be accessed directly by the user via the functions 
described below. It should be noted that interscope actually creates two data 
bases, the first containing information about the elementary relations between 
the functions and variables in the user's system, and the second containing 
information derived from the first, i.e. the paths by which one function calls 
another. The first data base is created when interscope analyzes a system (via 
the function lookat ) . The second data base is developed incrementally (by the 
function paths ), depending on the questions asked by the user. Both data bases 
are stored on the property lists of the functions and variables which are 
analyzed. 



Since the data base that Interscope constructs is global (stored on 
property lists), the user can also exit from interscope , either by typing 
OK or GOODBYE, or via control-D, and then reenter interscope at some later 
point and continue asking questions, without having to reanalyze his 
functions . 



The translation of the most recent input is always stored in the function 
definition cell of the atom MEANING. 

Whore possible, interscope will try to inform the user what part of the 
sentence it did not understand. 
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Interscope "understands" a wide variety of the elementary relations that exist 

between functions and variables, e.g. which functions bind, use, change, test, 

or smash a given variable, which functions may cause a given function to be 

IP 

called, either directly or indirectly, which variables are used as global or 
local free variables, either by a given function or by a group of functions, 
etc . 

Information about the function-call paths from one program to another is 
"generalized" when it is stored; e.g. at [5] in Figure 20-3, one of the paths 
by which CLISPATOM calls LISTP is given as (CLISPATOM *«* RETDWIM «** LISTP), 
which means that there is more than one path from CLISPATOM to RETDWIM, and 
more than one path from RETDWIM to LISTP. 

The conventions used by Interscope for recognizing functions that are 
"uninteresting" are the same as those used by printstructure (page 20.3), i.e. 
yesfns , nofns f irstfn , and lastfn all have the same effect as for 
printstructure . 



Interscope Functions 

paths[x;y;type;must;avoid;only] Value is a list of paths from x to ^, where 

each path is an ordered list of functions. *** is 
used to indicate multiple paths. For example, if 
FOO calls FIE, and FIE calls FUM directly as well 
as calling FIEl which calls FUM, then 
paths[FOO;FUN] returns ((FOO FIE *** FUM)). 



e.g. if FOO calls FIE, and FIE calls FUN, then FOO calls FUM indirectly. 
'SOMEHOW' means directly or indirectly, e.g. 

"WHAT FUNCTIONS CALL FOO SOMEHOW?" 
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type , must , avoid , and only are optional, type can 
be either CALLS or CALLEOBY (NIL is equivalent to 
CALLS), e.g. in the above example, 
paths[FUM;FOO;CALLEDBY] would return the same set 
of paths as paths[F00;FUN3, except each path would 
be in the reverse order. 

must , avoid , and only are used to select out 
certain types of paths. Each can be specified by 
an atom which evaluates to a list of functions, or 
a form which evaluates to such a list. If (the 
value of) must is non-NIL, each path is required 
to go through at least one of the members of must . 

avoid is non-NIL, no path can go through any 
member of avoid . If only is non-NIL, no path can 
go through any function which is not a member of 
only , i.e. each path can only go through functions 
on only . 

treepaths[x;y;type;must;avoid;only] Like paths , except prints paths as a 

tree structure, as shown at [6] in Figure 20-3. 
type , must, avoid , and only have the same meaning 
as with paths . 
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paths is called for English inputs of the form: 
"WHAT ARE THE PATHS FROM X TOy?". Such questions can be modified with 
subordinate clauses to indicate values for must , avoid , and/or only , e.g. 
"WHAT ARE THE PATHS FROM FOO TO FIE WHICH ONLY GO THROUGH FOOFNS AND AVOID 
FIEFNS?" 

treepaths is called for English inputs of the form "SHOW ME HOW x CALLS y", 
"DISPLAY THE PATHS FROM x TO y", etc. 
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lookat[x] Builds the initial data base describing the system 

X, where x is either the name of a function, the 
name of a variable which evaluates to a list of 
functions, or the list of functions itself. 

clumpgetC object ;relation;universe3 Value is a list of objects (functions or 

variables) which have the indicated relation with 
respect to object , e.g. cluropget[FOO*, CALLERS] 
returns a list of functions that call FOO, 
clumpget[X;SMASHERS] a list of functions that 
smash the variable X, etc. A complete list of the 
possible values for relation is given below. ■'^ 

object can be a list of objects (or a variable 
which evaluates to a list of objects), in which 
case the value returned by clumpget is the list of 
all objects which have the indicated relation to 
awj/ of the members of object . 

Similarly, universe can be a list of objects (or a 
variable which evaluates to a list of objects), in 
which case the value returned by clumpget is the 
list of all objects in universe which have the 
indicated relation to object (or any of the 
members of object ), e.g. 

c lumpge t[ X ;SNASHERS ; FOOFNS ] . 



^lii!P_RU.?Ji is given a value for relation that it does not recognize, it 

will attempt spelling correction, and if that fails, generate an error. If 

given a value for object that it has not seen before, it will type "I don't 

know anything about object, shall I analyse a system?" and go into analysis 
modo . 
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Finally,, universe can be a relation, which is 
equivalent to supplying clumpget[ object ;universe] 
in place of object , i.e. the value returned is the 
list of all objects which have the indicated 
relation to any of the members of the {set of all 
objects which bear the relationship universe to 
object } . For example, 

clumpget[FOO;CALLERS;CALLEDFNS] is a list of all 
functions that call any of the functions (CALLERS) 
that are directly called by FOO (CALLEDFNS). 
c1umpget[F00;FREEUSERS;L0CALVARS3 is a list of 
functions that use freely any of the variables 
that are bound locally by FOO. 



Currently, the following relations are implemented: 



CALLERS 



list of functions that directly call object , 



CALLEDFNS 



list of functions directly called by object 



CALLCAUSERS 



list of functions that call object , perhaps 
indirectly. In English: "WHO CALLS FOO SOMEHOW?". 



CALLSCAUSED 



list of functions called by object , perhaps 
indirectly. In English: "WHO DOES FOO CALL 
SOMEHOW?" 



ABOVE 



union of object with CALLCAUSERS, 



BELOW 



union of object with CALLSCAUSED, 



ARGS 



arguments of object . 
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ARGBINOERS 



list of functions that have object as an argument. 



LOCALVARS 



list of variables that are locally bound in 
object , e.g. PROG vars. 



LOCALBINDERS 



list of functions that bind object as a local 
variable. 



FREEVARS 



list of variables used freely by object . 



FREEUSERS 



list of functions .that use object freely, 



LOCALFREEVARS 



list of variables that are used freely In object , 
but are bound in object before they are used, e.g. 

clumpgetCFOO; LOCALFREEVARS; BELOW] gives a list of 

those variables used freely below FOO, but are 

//I 

bound above the place that they are used. In 
English: "WHAT ARE THE LOCAL FREE VARS (VARIABLES) 
BELOW FOO?" 



GLOBALFREEVARS 



list of variables used freely in object without 
previously being bound in object . 



ENTRYFNS 



list of each function in object which is not 
called by any function in object other than 
itself, e.g. clumpget[FOOFNS; ENTRYFNS]. 
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Note that if object is the name of a function and universe is NIL, 
LOCALFREEVARS will always be NIL, and GLOBALFREEVARS the same as FREEVARS. 
It is only in connection with collections of functions that LOCALFREEVARS 
and GLOBALFREEVARS become interesting. 
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SELFRECURSIVE 



list of functions in object which call themselves 
directly. 



CAUSESELFCALL list of functions in object which could call 

themselves, perhaps Indirectly. 

CAUSERECURSION list of functions in object which cause some 

function to call itself, perhaps indirectly. 

CHANGEVARS list of variables that are changed by object , 

where 'changed' means any flavor of assignment, 
i.e. via SETQ. SETOO, RPAQ, SETN, or even an 
expression of the form (RPLACA (QUOTE atom) value) 
(or FRPLACA, /RPLACA, SAVESET, etc.)^^ 

CHANGERS list of functions that change object . 

Note: 'set' in English input means any flavor of assignment, and translates the 
same as ' change* . 



SMASHVARS list of variables whose value are smashed by 

object , where 'smash' means the variable appears 

as the first argument to one of the list of 

IS 

functions on smasherslst. 



clumpget will accept as relations SETQVARS, SETQERS. SETVARS. SETTERS, 

SETQQERS, SETQQVARS, etc., in case the user wants to distinguish between 

the various flavors of assignments. In English, "WHAT ARE THE SETQERS OF 
X?", etc. 



Initially (RPLACA RPLACD FRPLACA FRPLACO /RPLACA /RPLACD NCONC NCONCl 
/NCONC /NCONCl ATTACH /ATTACH RPLNODE /RPLNODE RPLNO0E2 /RPLN0DE2). As 
with assignments, clumpget will accept as relations RPLACAERS, RPLACAVARS, 
RPLACOERS, RPLACDVARS, etc., in case the user wants to distinguish the 
different types of smashing. 
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list of functions that smash object . 



list of variables that are tested by object , where 
'tested' means they appear as the first argument 
to one of the list of functions on tcsterslst , 
initially (ATOM LISTP NUMBERP NLISTP STRINGP EQ 
EQP EQUAL NULL)» or anywhere in an AND or OR, or 
as the predicate in a CONO clause, or as the first 
argument to SELECTQ, etc. 

list of functions that test object . 

list of variables that are used in object , where 
'used* means actually appear in the body of the 
function, i.e. if a variable is simply bound, but 
not actually used anywhere, it will not be 
included in the value of USEVARS. CHANGEVARS and 
TESTVARS are subsets of USEVARS. 

list of functions that use object . 
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Index for Section 20 



Page 
Numbers 

ALLCALLS[FN;TREELST] Z0.9 

CALLS[FN;EXPRFLG;VARSFLG] \ 20.10 

CLISP 20.5 

CLUMPGET[OBJECT;RELATION;UKIVERSE] 20.17 

debugging 20.5 

DONELST (printstructure variable/parameter) -20.8 

DWIMIFY[X;L] 20.5 

EXPR (property name) 20.7 

EXPRFLG (printstructure variable/parameter) 20.6,9 

FIRSTFN[FN] 20.4,9 

FREEVARS[FN;EXPRFLG'] 20.10 

INTERSCOPE 20.11''21 

IS NOT DEFINED (typed by PRINTSTRUCTU^^ 20^5 
LAST-PRINTSTRUCTURE 

(printstructure variable/parameter) 20.6,8-9 

LASTFNCFN] 20.4.9 

LOOKAT[X] 20.13,17 

NIL: 20.6 

NOFNS (printstructure variable/parameter) 20.3 

NOTRACEFNS (printstructure variable/parameter) .. 20.4 

P.P.E. (typed by PRINTSTRUCTURE) 20.5,8 

PATHSC X ; Y ; TYPE ;MUST ; AVOID ;ONLY] 20 . 14- 15 

PRDEPTH (printstructure variable/parameter) 20.4 

PRINTSTRUCTURECX;EXPRFLG;FILE] 20.1-10 

QUOTEFNS (printstructure variable/parameter) .... 20.4 

TENEX 20.6 

TREELST (printstructure variable/parameter) 20.8 

TREEPATHS[X;Y;TYPE;MUST;AVOID;ONLY] 20.16 

TREEPRINT[X;N] 20.9 

VARPRINT[D0NELST;TREELST3 20.9 

VARS[ FN; EXPRFLG] 20.10 

YESFNS (printstructure variable/parameter) ...... 20.3 

(In interscope output) 20.15 

«*CUTOFF«« (typed by PRINTSTRUCTURE) 20.4 
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SECTION 21 
MISCELLANEOUS 



21.1 Measuring Functions 



time[ tiinex;tinien;tinietyp] is an nlarobda function. It executes the 

computation timex, and prints out the number of 
conses and computation time. Garbage collection 
time is subtracted out. 



-TIME((LOA0 (QUOTE PRETTY) (QUOTE PROP] 
FILE CREATED 7-MAY-71 12:47:14 

GO: 8 

582, 10291 FREE WORDS 

PRETTYFNS 

PRETTYVARS 

3727 CONSES 

10.655 SECONDS 

PRETTY 



If timen is greater than 1 ( tlmen =NIL equivalent 
to tiroen sl). time executes timex timen number of 
times and prints out number of conses/timen, and 
computation time/timen. This is useful for more 
accurate measurement on small computations, e.g. 



♦-TIME((COPY (QUOTE (A B C))) 10) 
30/10 = 3 CONSES 
.055/10 » .0055 SECONDS 
(A B C) 
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If tiroetype is 0, time measures and prints total 
real time as well as computation time, e.g. 



«-TIME((LOAD (QUOTE PRETTY) (QUOTE PROP)) 1 0] 
FILE CREATED 7-NAY-71 12:47:14 

GC: 8 

!382, 10291 FREE WORDS 

PRETTYFNS 

PRETTYVARS 

3727 CONSES 

11.193 SECONDS 

27.378 SECONDS, REAL TIME 

PRETTY 



If timetyp » 3, time measures and prints garbage 
collection time as well as computation time, e.g. 



*-TIME((LOAD (QUOTE PRETTY) (QUOTE PROP)) 1 3] 
FILE CREATED 7-MAY-71 12:47:14 

GC: 8 

!}82, 1091 FREE WORDS 
PRETTYFNS 
PRETTYVARS 
3727 CONSES 
10.597 SECONDS 

1.487 SECONDS, GARBAGE COLLECTION TIHE 
PRETTY 



Another option is timetype sT. in which case time 
measures and prints the number of pagefaults. 

The value of time is the value of the last 
evaluation of timex. 



If ac3 »NIL. obtains date and time from TENEX and 
returns it as single string in format "dd-mm>yy 
hh:mm:ss", where dd is day, mm is month, yy year, 
hh hours, mm minutes, ss seconds, e.g., 
"14-MAY-71 14:26:08". 
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other values of ac3 can be used to specify other 
formats, e.g. day of week, time zone, etc. as 
described in TENEX JSYS Manual. 



clockCn] for n»0 



for n«l 



for n=2 



for n=3 



current value of the time of day clock 
i.e., number of milliseconds since last 
system start up. 

value of the time of day clock when the 
user started up this INTERLISP, i.e., 
difference between clock[0] and clock[l] 
is number of milliseconds (real time) 
since this INTERLISP was started. 

number of milliseconds of compute time 
since user started up this INTERLISP 
(garbage collection time is subtracted 
off). 

number of milliseconds of compute time 
spent in garbage collections (all 
types )J 



disroiss[n] dismisses program for n milliseconds, during which 

time program is in a state similar to an I/O wait, 
i.e., it uses no CPU time. Can be aborted by 
control-D, control-£, or control-B. 



This number is directly accessible via the COREVAL GCTIN. 
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conscount[n] conscount[] returns the number of conses since 

INTERLISP started up. If n is not NIL, resets 

conscount to n. 

boxcount[type;n] number of boxing operations (see Section 13) sit\ce 

INTERLISP started up. If type sNIL, returns number 
of large integer boxes; typeaFLOATING, returns 
number of floating boxes. ^ If n is not NIL, 
resets the corresponding counter to n. 



gctrpC] number of conses to next GC: 6, i.e., number of 

list words not in use. Note that an intervening 
GC of another type could collect as well as 
allocate additional list words. See Section 3. 

gctrp[n] can be used to cause an interrupt when 
value of gctrpOn, see Section 10. 

pagefaults[] number of page faults since INTERLISP started up. 

logoutC] returns to TENEX.^ A subsequent CONTINUE command 

will enter the INTERLISP program, return NIL as 
the value of the call to logout , and continue the 
computation exactly as if nothing had happened, 
i.e., logout is a programmable control>C. As with 
control-C, a REENTER command following a logout 
will reenter INTERLISP at the top level. 



These counters are directly accessible via the COREVALs IBOXCN and FBOXCN. 

If INTERLISP was started a» a subsidiary fork (see subsys . page 21.18), 
control is returned to the higher fork. 
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logout[] will not affect the state of any open 
files. 



21.2 Breakdown' 



Time gives analyses by computation. Breakdown is available to analyze the 
breakdown of computation time (or any other measureable quantity) function by 
function. The user calls breakdown giving it a list of functions of interest. 
These functions are modified so that they keep track of the "charge" assessed 
to them. The function results gives the analysis of the statistic requested as 
well as the number of calls to each function. Sample output is shown below. ^ 



*-BREAKDOWN(SUPERPRINT SUBPRINT COMMENTl) 

(SUPERPRINT SUBPRINT COMHENTl) 

-PRETTYOEF( (SUBPRINT) FOO) 

(SUBPRINT) 

-RESULTSO 

FUNCTIONS TIME # CALLS 

SUPERPRINT 25.294 458 
SUBPRINT 32.96 169 

COMMENTl 7.833 12 

TOTAL 66.087 639 

NIL 



The procedure used for measuring is such that if one function calls other and 

both are 'broken down', then the time (or whatever quantity is being measured) 
spent in the inner function is not charged to the outer function as well. 



breakdown was written by W. Teitelman. 



This is with an interpreted prettyprint . 



breakdown will not give accurate results if a function being measured is 
not returned from normally, e.g. a lower retfrom (or error ) bypasses it. 
In this case, all of the time (or whatever quantity is being measured) 
between the time that function is entered and the time the next function 
being measured is entered will be charged to the first function. 
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To remove functions from those ibeing monitored, simply unbreak the functions, 
thereby restoring them to their original state. To add functions, call 
breakdown on the new functions. This will not reset the counters for any 
functions not on the new list. However breakdown[] can be used for zeroing the 
counters of all functions being monitored. 

To use breakdown for some other statistic, before calling breakdown . set the 
variable brkdwntype to the quantity of interest, e.g., TIME, CONSES, etc. 
Whenever breakdown is called with brkdwntype not NIL, breakdown performs the 
necessary changes to its internal state to conform to the new analysis. In 
particular, if this is the first time an analysis is being run with this 
statistic, the compiler may be called to compile the measuring function. When 
breakdown is through initializing, it sets brkdwntype back to NIL. Subsequent 
calls to breakdown will measure the new statistic until brkdwntype is again set 
and a new breakdown performed. Sample output is shown below: 

-SET( BRKDWNTYPE CONSES) 
CONSES 

«-BREAKDOWN(MATCH CONSTRUCT) 
(MATCH CONSTRUCT) 

-FLIP((A B C D E I- G H C Z) (.. SI .. #2 ..) (.. #3 ..)) 
(A B D E F G H Z) 
^RESULTS( ) 

FUNCTIONS CONSES # CALLS 

MATCH 32 1 

CONSTRUCT 47 1 

TOTAL 79 2 

NIL 

The value of brkdwntype is used to search the list brkdwntypes for the 
information necessary to analyze this statistic. The entry on brkdwntypes 
corresponding to brkdwntype should be of the form (type form function), where 
form computes the statistic, and function (optional) converts the value of form 
to some more interesting quantity, e.g. 



The measuring functions for TINE and CONSES have already been compiled. 
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(TIME (CLOCK 2) (LAMBDA (X) (FQUOTIENT X 1000)))^ measures computation time and 
reports the result in seconds instead of milliseconds. If brkdwntype is not 
defined on brkdwntypes , an error is generated, brkdwn types currently contains 
entries for TIME, CONSES, PAGEFAULTS, BOXES, and FBOXES. 



More Accurate Measurement 

Occasionally, a function being analysed is sufficiently fast that the overhead 
involved in measuring it obscures the actual time spent in the function. If 
the user were using time, he would specify a value for timen greater than 1 to 
give greater accuracy. A similar option is available for breakdown . The user 
can specify that a function(s) be executed a multiple number of times for each 
measurement, and :the average value reported, by including a number in the list 
of functions given to breakdown , e.g., BREAKDOWN (EO I TCOM EDIT4F 10 E0IT4E EQP) 
means normal breakdown for editcom and edit4f but executes (the body of) edit4e 
and eqp 10 tiroes each time they are called. Of course, the functions so 
measured roust not cause any harmful side effects, since they are executed more 
than once for each call. The printout from results will look the same as 
though each function were run only once, except that the measurement will be 
more accurate. 



For more accurate measurement, the form for TIME is not (CLOCK 2) but 
(ASSEMBLE NIL (MOVE I 1 , -5) (JSYS 13) (SUB 1 , GCTIM)). 
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21.3 Edita 



Edita is an editor for arrays. However, its most frequent application is in 
editing compiled functions (which are also arrays in INTERLISP), and a great 
deal of effort in implementing edita . and most of its special features* are in 
this area. For example, edita knows the format and conventions of INTERLISP 
compiled code, and so, in addition to decoding instructions a la DOT»^^ edita 
can fill in the appropriate COREVALS, symbolic names for index registers, 
references to literals, linked function calls, etc. The following output shows 
a sequence of instructions in a compiled function first as they would be 
printed by DDT, and second by edita. 



466716/ 


PUSH 


16,LISP&KNIL 


3/ 


PUSH PP,KNIL 


466717/ 


PUSH 


16,LISP&KNIL 


4/ 


PUSH PP.KNIL 


466720/ 


HRRZ 


1.-12(16) 


5/ 


HRRZ 1,-10(PP) 


466721/ 


CAME 


1,LISP&KNIL 


6/ 


CAME 1,KNIL 
JRST 9 


466722/ 


JRST 


466724 


7/ 


466723/ 


HRRZ 


1.0467575 


8/ 


HRRZ 1,@'BRKFILE 


466724/ 


PUSH 


16,1 


9/ 


PUSH PP,1 


466725/ 


LISP&IOFIL,. 467576 


10/ 


PBIND 'BRKZ 


466726/ 


-3.,- 


•3 


11/ 


-524291 


466727/ 


HRRZ 


1.-14(16) 


12/ 


HRRZ 1,-12(PP) 


466730/ 


CAMN 


1,467601 


13/ 


CAMN 1,'OK 


466731/ 


JRST 


466734 


14/ 


JRST 17 


466732/ 


CAME 


1.467602 


15/ 


CAME 1,'STOP 


466733/ 


JRST 


466740 


16/ 


JRST 21 


466734/ 


PUSH 


16,467603 


17/ 


PUSH PP.'BREAKl 


466735/ 


PUSH 


16.467604 


18/ 


PUSH PP, '(ERROR!) 
CCALL 2,'RETEVAL 


466736/ 


LISP&FILEN,, 467605 


19/ 


466737/ 


JRST 


467561 


20/ 


JRST 422 


466740/ 


CAME 


1,467606 


21/ 


CAME 1,'GO 


466741/ 


JRST 


466754 


22/ 


JRST 33 


466742/ 


HRRZ 


1,9-12(16) 


23/ 


HRRZ 1,9-10(PP) 


466743/ 


PUSH 


16,1 


24/ 


PUSH PP.l 



edita was written by W. Teitelman. 



DDT is one of the oldest debugging systems still around. For users 
unfamiliar with it, let us simply say that edita was patterned after it 
because so many people are familiar with it. 

Note that edita prints the addresses of cells contained tn the function 
relative to the origin of the function. 
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Therefore, rather than presenting edita as an array editor With some extensions 
for editing compiled code, we prefer to consider it as a facility for editing 
compiled code, and point out that it can also be used for editing arbitrary 
arrays , 



Overview 

To the user, edita looks very much like DDT with INTERLISP extensions. It is a 
function of one argument, the name of the function to be edited. Individual 

registers or cells in the function may be examined by typing their address 

13 

followed by a slash, e.g. 

6/ HRRZ 1,-10(PP) 

The slash is really a command to edita to open the indicated register. Only 
one register at a time can be open, and only open registers can be changed. To 
change the contents of a register, the user first opens it, types the new 
contents, and then closes the register with a carriage-return, e.g. 

7/ CAMEl,'t CAMN l.'r^ 



An optional second argument can be a list of commands for edita. These are 
then executed exactly as though they had come from the teletype. 
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Underlined characters were typed by the user. edita uses its own read 
program, so that it is unnecessary to type a space before the slash or to 
type a carriage return after the slash. 

edita also converts absolute addresses of cells within the function to 
relative address on input. Thus, if the definition of foo begins at 85660, 
typing 6/ is exactly the same as typing 85666/. 

Since carriage-return has a special meaning, edita indicates the balancing 
of parentheses by typing a space. 
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If the user closes a register without specifying the new contents, the contents 
are left unchanged. Similarly, if an error occurs or the user types control-E, 
the open register, if any, is closed without being changed. 

Input Protocol 

Edita processes all inputs not recognized as commands in the same way. If the 
input is the name of an instruction (i.e. an atom with a numeric OPD property), 
the corresponding number is added to the input value being assembled, and a 
flag is set which specifies that the input context is that of an instruction. 

The general form of a machine instruction is (opcode ac , 9 address (index)} as 
described in Section 18. Therefore, in instruction context, edita evaluates 
all atoms (if the atom has a COREVAL property, the value of the COREVAL is 

17 

used), and then if the atom corresponds to an ac,' shifts it left 23 bits and 
adds it to the input value, otherwise adds it directly to the input value, but 
performs the arithmetic in the low 18 bits.^ Lists are interpreted as 
specifying index registers, and the value of car of the list (again COREVALs 
are permitted) is shifted left 18 bits. Examples: 



16 
17 

18 



The input value is initially 0. 

i.e. if a has not been seen, and the value of the atom is less than 16, 
oner the low 18 bits of the input value are all zero. 

If the absolute value of the atom is greater than lOOOOOOQ, full word 
arithmetic is used. For example, the indirect bit is handled by simply 
binding 9 to 20000000Q. 
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PUSH PP. KNIL 
HRRZ I.-IO(PP) 
CAME 1. 'GO 
ORST 33 ORG 

The user can also specify the address of a literal via the ' command* see page 
21.14. For example. if the literal "UNBROKEN" is in cell 85672, 
HRRZ 1.'* UNBROKEN" is equivalent to HRRZ 1, 85672. 

When the input context is not that of an instruction, i.e. no OPO has been 
seen, all inputs are evaluated (the value of an atom with a COREVAL property is 
the COREVAL.) Then numeric values are simply added to the previous input value; 
non-numGric values become the input value. 

The only exception to the entire procedure occurs when a register is open that 
is in the pointer region of the function, i.e. literal table. In this case, 
atomic inputs are not evaluated. For example, the user can change the literal 
FOO to FIE by simply opening that register and then typing FIE followed by 
carriage-return, e.g. 

'FOO/ FOO FIE^ 
Note that this is equivalent to 'FOO/ FOO (QUOTE FIE)) 
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edita cannot in general know whether an address field in an instruction 
that is typed in is relative or absolute. Therefore, the user must add 
ORG, the origin of the function, to the address field himself. Note that 
edita would print this instruction, JRST 53 ORG, as JRST 53. 

Presumably there is only one input in this case. 
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Edita Commands and Variables 



^ (carriage-return) 



If a register is open and an input was tXDed» 
store the input in the register and close it. 

If a register is open and nothing was typed, close 
the register without changing it. 

If a register is not open and input was typed, 
type its value. 



ORG 



Has the value of the address of the first 
instruction in the function, i.e. loc of getd of 
the function. 



Opens the register specified by the low .18 bits of 
the quantity to the left of the /, and types its 
contents. If nothing has been typed, it uses the 
last thing typed by edita. e.g. 



35/ JRST 53 



CAHE 1,* RETURN 



RETURN 



If a register was open, / closes it without 
changing its contents. 

After a / command, edita returns to that state of 
no input having been typed. 



tab (control- I) 



Same as carriage-return, followed by the address 
of the quantity to the left of the tab, e.g. 



35/ ORST 53 tab 
537 CAHE 1, 'RETURN 



Note that if a register was open and input was typed, tab will change the open 
register before closing it, e.g. 



35/ ORST 53 
54/ ORST 70 
35/ ORST 54 



ORST 54 tab 



(period) 



has the value of the address of the current (last) 
register examined. 
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If the register is in the unboxed region of the function, the unboxed value 
is stored in the register. 
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line-feed 



same as carriage-return followed by (ADO 1 .)/ i.e. 
closes any open register and opens the next 
register. 



same as carriage-return followed by (SUBl .)/ 



SQ (alt-modeQ) 



has as its value the last quantity typed by edita 
e.g. 



35/ JRST 53 SQ 1^ 
./ ORST 54 



LITS 



has as value the (relative) address of the first 
literal. 



BOXED 

S (dollar) 



same as LITS 



has as value the relative address of the last 
literal in the function. 



•5®^* radix to -8 and types the quantity to the 
left of the s sign, i.e. if anything has been 
typed* types the input value, otherwise, types SQ, 
e.g. 



35/ JRST 54 -254000241541Q JRST 54=254000000066Q 



Following s, radix is restored and edita returns 
to the no input state. 



OK 
? 



leave edita 



return to 'no input' state. 7 is a 'weak' 
control-E, i.e. it negates any input typed, but 
does not close any registers. 



addressl, address2/ 



prints the contents of registers addressl 
through address2 . . is set to address2 after the 
completion. 
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output goes to file , initially set to T. The user can also set file (while 
edita ) to the name of a disc file to redirect the output. (The user is 
responsible for opening and closing file .) Note that file only affects 
output for the addressl, address2/ command. 
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•x corresponds to the • in LAP. The next expression 

is read, and if it is a small number, the 
appropriate offset is added to it. Otherwise, the 
literal table is searched for x, and the value of 
'X is the (absolute) address of that cell. An 
error is generated if the literal is not found, 
i.o. ' cannot be used to create literals. 

:atoin defines atom to an address 

(1) the value of $Q if a register is open, 

(2) the input if any input was typed, 
otherwise 

(3) the value of '.'.^^ 
For example : 



35/ JRST 54 ;F00^ 
FIE/ JRST FOO .-35 



Edita keeps its symbol tables on two free variables, usersyms and symlst . 
Usersyms is a list of elements of the form (name . value) and is used for 
encoding input, i.e., all variables on usersyms are bound to their 
corresponding values during evaluation of any expression inside edita . Symlst 
is a list of elements of the form (value . name) and is used for cfecoding 
addresses. Usersyms is initially NIL, while symlst is set to a list of all the 
corevals . Since the : command adds the appropriate information to both these 
two lists, new definitions will remain in effect even if the user exits from 
edita and then reenters it later. 

Note that the user can effectively define symbols without using the : command 
by appropriately binding usersyms and/or symlst before calling edita. Also, he 
can thus use different symbol tables for different applications. 

SW (alt-modeW) search command. 

Searching consists of comparing the object of the search with the contents of 
each register, and printing those that match, e.g. 



Only the low 18 bits are used and converted to a relative address whenever 

possible. 
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HRRZ g 

8/ HRRZ 1,0'BRKFILE 
23/ HRRZ 1,©-10(PP) 
28/ HRRZ l,e-12(PP) 

The SW command can be used to search either the unboxed portion of a function, 
i.e. instructions, or the pointer region, i.e. literals, depending on whether 
or not the object of the search is a number. If any input was typed before the 
SW, it will be the object of the search, otherwise the next expression is read 
and used as the object .^^ The user can specify a starting point for the search 
by typing an address followed by a ',' before calling SW, e.g. 1, JRST SW. If 
no starting point is specified, the search will begin at 0 if the object is a 
number, otherwise at LITS, the address of the first literal .^^ After the search 
is completed, '.' is set to the address of the last register that matched. 

If the search is operating in the unboxed portion of the function, only those 
fields (i.e. instruction, ac, indirect, index, and address) of the object that 

PR 

contain one bits are compared. For example, HRRZ @ SW will find all instances 
of HRRZ indirect, regardless of ac, index, and address fields. Similarly, 
'PRINT SW will find all instructions that reference the literal PRINT.'^^ 
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27 



Note that inputs typed before the SW will have been processed according to 
the input protocol, i.e. evaluated; inputs typed after the SW will not. 
Therefore, the latter form is usually used to specify searching the 
literals, e.g. SW FOO is equivalent to (QUOTE FOO) SW. 

Thus the only way the user can search the pointer region for a number is to 
specify the starting point via 

Alternately, the user can specify his own mask by setting the variable mask 
(while in edita ), to the appropriate bit pattern. 

The user may need to establish instruction context for input without giving 
a specific instruction. For example, suppose the user wants to find all 
instructions with ac^l and indexsPP. In this case, the user can give & as 
a pseudo-instruction, e.g. type & 1, (PP). 
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If the search is operating in the pointer region, a 'match' is as defined in 
the editor. For example, SW (&) will find all registers that contain a list 
consisting of a single expression. 



SC (alt-roodeC) like SW except only prints the first match, then 

prints the number of matches when the search 
finishes. 



Editing Arrays 

Edita is called to edit a function by giving it the name of the function. 
Edita can also be called to edit an array by giving it the array as its first 
argument,^ in which case the following differences are to be noted: 



1. decoding - The contents of registers in the unboxed region are boxed 
and printed as numbers, i.e. they are never interpreted as 
instructions, as when editing a function. 

2. addressing convention - Whereas 0 corresponds to the first instruction 
of a function, the first element of an array by convention is element 
number 1. 

3. input protocols - If a register is open, lists are evaluated, atoms 
are not evaluated (except for SQ which is always evaluated). If no 
register is open, all inputs are evaluated, and if the value is a 
number, it is added to the 'input value'. 

4. left half - If the left half of an element in the pointer region of an 
array is not all O's or NIL, it is printed followed by a e.g. 



the array itself, not a variable whose value is an array, e.g. (EOITA FOO), 

not EDITA(FOO). 
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10/ (A B) ; T 



Similarly, if a register is closed, either its left half, right half, 
or both halves can be changed, depending on the presence or absence, 
and position of the ; e.g. 



10/ 


(A B) ; T 


B;^ changes left 


d. 


B ; T 


NIL^ changes right 


d. 


B ; NIL 


A : changes both 


J, 


A ; C 





If ; is used in the unboxed portion of an array, an error will be 
generated. 

The SW command will look at both halves of elements in tjie pointer region, and 
match if either half matches. Note that SW A ; B is not allowed. 

This ends the section on edita . 
21.4 Interfork Communication 

The functions described below permit two forks (one or both of them INTERLISP) 
to have a common area of address space for communication by providing a means 
of assigning a block of storage guaranteed not to move during garbage 
collections * 

getblk[n] Creates a block n pages in size (512 words per 

page). Value is the address of the first word in 
the block, which is a multiple of 512 since the 
block will always begin at a page boundary. If 
not enough pages are available, generates the 
error ILLEGAL OR IMPOSSIBLE BLOCK. 
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Hfotet the block con be used for storing unboxed numbers onlu . 



To store a number in the block, the following function could be used: 

[SETBLOCK (LAMBDA (START N X) (CLOSER (IPLUS (LOC START) N) X] 

Some boxing and unboxing can be avoided by making this function compile open 
via a substitution macro. 

Motet getblk should be used spa ring I if since several unmovable regions of memory 
can make it difficult or impossible for the garbage collector to find a 
contiguous region large enough for expanding array space, 

relblkC address ;n] releases a block of storage beginning at address 

and extending for n pages. Causes an error 
ILLEGAL OR IMPOSSIBLE BLOCK if any of the range is 
not a block. Value is address . 

21.5 Subsys^ ^ 

This section describes a function, subsys , which permits the user to run a 
TENEX subsystem, such as SNDNSG, SRCCON, TECO, or even another INTERLISP, from 
inside of an INTERLISP without destroying the latter. In particular, 
SUBSYS(EXEC) will start up a lower exec, which will print the TENEX herald, 
followed by 9. The user can then dp anything at this exec level that he can at 
the top level, without affecting his superior INTERLISP. For example, he can 
start another INTERLISP, perform a sysin , run for a while, type a control-C 
returning him to the lower exec, RESET, do a SNDNSG, etc. The user exits from 
the lower exec via the command QUIT, which will return control to subsys in the 



subsys was written by J.W. Goodwin. 
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higher INTERLISP. Thus with subsys , the user need not perforin a sysout to save 
the state of his INTERLISP in order to use a TENEX capability which would 
otherwise clobber the core image. Similarly, subsys provides a way of checking 
out a sysout file in a fresh INTERLISP without having to commandeer another 
teletype or detach a Job. 

While subsys can be used to run any TENEX subsystem directly, without going 
through an intervening exec, this procedure is not recommended. The problem is 
that control-C always returns control to the next highest exec. Thus if the 
user is running an INTERLISP in which he performs SUBSYS(LISP), and then types 
control-C to the lower INTERLISP, control will be returned to the exec above 
the first INTERLISP. The natural REENTER command would then clear the lower 
INTERLISP,^^ but any files opened by it would remain open (until the next 
PRESET). If the user elects to call a subsystem directly, he must therefore 

31 

know how it is normally exited and always exit from it that way. 

Starting a lower exec does not have this disadvantage, since it can only be 
exited via QUIT, i.e., the lower exec is effectively 'errorset protected* 
against control-C. 

subsys[ file/fork ;incomf lie ;outcomfile',entrypointflg] 

filo/fork sEXEC, starts up a lower exec, 
otherwise runs <SUBSYS>system, e.g. 

subsys[SNDMSG],subsys[TECO] etc. susbys[ ] is same 
as subsys[ EXEC ] . Control-C always returns control 



A CONTINUE command however will return to the subordinate program, i.e. 
control-C followed by CONTINUE is safe at any level. 

INTERLISP is exited via the function logout , TECO via the command ;H, 
SNDNSG via control-Z, and EXEC via QUIT. 
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to next higher exec. Note that more than one 
INTERLISP can be stacked, but there is no 
backtrace to help you figure out where you are. 

incoinfile and outcoinfile provide a way of 
specifying files for input and output, incoinfile 
can also be a string, in Which case a temporary 
file is evaluated, and the string printed on it. 

entrypointflg may be START, REENTER, or CONTINUE. 
NIL is equivalent to START, except when file/fork 
is a handle (see below) in which case NIL is 
equivalent to CONTINUE. 

The value of subsys is a large integer which is a handle to the lower fork. 
The lower fork is not reset unless the user specifically does so using kfork, 
described below. If susbys is given as its first argument the value of a 
previous call to subsys , it continues the subsystem run by that call. For 
example, the user can do (SETQ SOURCES (SUBSYS TECO)), load up the TECO with a 
big source file, massage the file, leave TECO with ;H, run INTERLISP for awhile 
(possibly including other calls to subsys ) and then perform (SUBSYS SOURCES) to 
return to TECO, where he will find his file loaded and even the TECO pointer 
position preserved. 



The fork is also reset when the handle is no longer accessible, i.e., when 
nothing in the INTERLISP system points to it. Note that the fork is 
accessible while the handle remains on the history list. 



Must be the exact same large number, i.e. §£. Note that if the user 
neglects to set a variable to the value of a call to subsys , (and has 
performed an intervening call so that sybsys[T] will not work), he can 
still continue this subsystem by obtaining the value of the call to subsys 
for the history list using the function valueof, described in Section 22. 
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Note that if the user starts a lower EXEC, in which he runs an INTERLISP, 
control-C's from the INTERLISP, then QUIT from the EXEC, if he subsequently 
continues this EXEC with subsys , he can reenter or continue the INTERLISP. 

Note also that calls to subsys can be stacked. For example, using subsys , the 
user can run a lower INTERLISP, and within that INTERLISP, yet another, etc., 
and ascend the chain of INTERLISPs using logout , and then descend back down 
again using subsys . 

For convenience, subsysCT] continues the last subsystem run. 

SNDMSG, LISP, TECO, and EXEC, are all LISPXMACROS which perform the 
corresponding calls to subsys . CONTIN is a LISPXMACRO which performs 
subsys[T], thereby continuing the last subsys . 

kfork[fork] accepts a value from subsys and kills it (RESET in 

TENEX terminology). If subsys[fork] is 
subsequently performed, an error is generated. 
kfork[T] kills all outstanding forks (from this 
INTERLISP). 



21.6 Miscellaneous Tenex Functions^ 

f ildir[f ilegroup] filegroup is a TENEX file group descriptor, i.e., 

it can contain stars, f ildir returns a list of 
the files which match filegroup , a la the TENEX 
DIRECTORY command, e.g. (FILOIR (QUOTE *.COM;0)). 



All of the functions in section 21.5, except for raise , lowercase , and 
tenex . were written by J.W. Goodwin. 



21.21 



loadavC] returns TENEX current load average as a floating 

point number (this number is the first of the 
three printed by the TENEX SYSTAT command). 

getab[tablename; index; formatflg] tablename may be any of the tables mentioned 

with SYSGT and GETAB in JSYS manual; and can be an 
atom or string. index is the index Into the 
table and must be a number, getab returns the 
value of that entry of that table as an integer 
unless formatflfls FLOATING, in which case the value 
is returned as a floating point number. For 
example, loadav is defined simply as: 
(GETAB (QUOTE SYSTAT) 12 (QUOTE FLOATING)). 
Similarly, the host number of the TENEX site you 
are logged in at may be obtained by 
(GETAB (QUOTE LHOSTN) 0). 

erstr[ern] ern is an error number from a JSYS fail return. 

ernsNIL means most recent error, erstr returns 

the TENEX error diagnostic as a string 
(from <SYSTEH>ERROR. MNEMONICS). 

raise[flg] raise[] informs TENEX that it should not raise 

lower case input, i.e., it is equivalent to 
logout[] 0NO RAISE, ©CONTINUE. raiseCT] informs 
TENEX that it should raise. raise[T] is the 
initial setting. The value of raise is the 



There are some tables in TENEX not documented in the JSYS manual, but getab 
works for these too if you should happen to hear about them. 
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previous setting. 



lowercase[f Ig] lowercase[T] performs raise[], sets Icasef Ig to 

fig , and performs other internal modifications to 
inform DWIN and CLISP that the user is running on 
a lowercase terminal. lowercase[] reverses the 
effect of lowercase[T]. The value of lowercase is 
its previous setting, lowercase is undoable. 

lowercase[T] also sets model33flg to NIL (see Section 17). Note that the user 
can be running on a lowercase terminal and still find it desirable to set 
inodel33flg to T if he thinks he is on a model 33, i.e. is used to running on 
one, and makes the typing errors associated with the keyboard layout on a model 
33. 

usernameCa] If a^NIL, returns login directory name; if a=T, 

returns connected directory name; if a is a 
number, username returns the user name 
corresponding to that user number. In all cases, 
the value is a string. 

usernumber[a] If asNIL, returns login user number; if a^T, 

returns connected user number; if a is a literal 
atom or' string, usernumber returns the number of 
the corresponding user, or NIL if no such user 
exists. 



raise also sets raisef Ig to fig so that the system can determine the 
raise-noralse state following sysin or reattaching to a detached Job, and 
restore the desired state. 
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Note: greeting (see Section ZZ) sets the variable usernarae to the login user 
name, and f irstname to the name used in the greeting. 



tenex[str] Starts up a lower EXEC (without a message) using 

subsys , and then unreads str, followed by "QUIT" 
(using bksysbuf . described in Section 14). For 
example, the LISPXNACRO SY which does a SYSTAT is 
implemented simply as TENEX["SY^"]. 

21.7 Printing Reentrant and Circular List Structures 

A reentrant list structure is one that contains more than one occurrence of the 
same (e£) structure. For example, tconc (Section 6) makes uses of reentrant 
list structure so that it does not have to search for the end of the list each 
time it is called. Thus, if x is a list of 3 elements, (ABC), being 
constructed by tconc, the reentrant list structure used by tconc for this 
purpose is: 



A 






B 






C 















FIGURE 21-1 
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This structure would be printed by print as ((A B C) C). Note that print would 
produce the same output for the non-reentrant structure: 




A 






B 






C 






— ► 









FIGURE 21-2 

In other words, print does not indicate the fact that portions of the structure 
in Figure 21-1 are identical. Similarly, if print is applied to a circular 
list structure (a special type of reentrant structure) it will never terminate. 

For example » if print is called on the structure: 




FIGURE 21-3 

it will print an endless sequence of left parentheses, and if applied to: 

FIGURE 21-4 

will print a left parenthesis followed by an endless sequence of A's. 
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The function circlprint described below produces output that will exactly 
describe the structure of any circular or reentrant list structure. This 
output may be in either single or double-line formats. Below are a few 
examples of the expressions that circlprint would produce to describe the 
structures discussed above. 



expression in Figure 21-1: 

single-line: ((A B *1* C) {1}) 

double-line: ((A B C) . {!>) 

1 



expression in Figure 21-3: 

single-line: {1}) 

double-line: ({1}) 
1 



expression in Figure 21-4: 

single-line: A . {1}) 

double-line: (A . {1}) 
1 
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Circlprint and circlmaker were written by P.C. Jackson. 
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The more complex structure: 




FIGURE 21-5 



is printed as follows: 

single-line: («2« {1} «3« {2) A «4* B . {3}) . (4)) 

double-line: ( ({1} {2} A B . {3}) . {4}) 
2 13 4 

In both formats, the reentrant nodes in the list structure are labeled by 
numbers. (A reentrant node is one that has two or more pointers coming into 
it.) In the single-line format, the label is printed between asterisks at the 
beginning of the node (list or tail) that it identifies. In the double-line 
format, the label is printed below the beginning of the node it identifies. An 
occurrence of a reentrant node that has already been identified is indicated by 
printing its label in brackets. 

circlprint[list;printflg;rlknt] prints an expression describing list . If 

printflg gNIL, double-line format is used, 
otherwise single-line format. circlprint first 
calls circlmark[list ;rlknt], and then calls either 
rlprinl[list] or rlprin2[list], depending on the 
value of prlntf Ig (T or NIL, respectively). 
Finally, rlrestore[list] is called, which restores 
list to its unmarked state. Value is list. 
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circlmarkC list ;rlknt] 



marks each reentrant node in list with a unique 
number, starting at rlknt' fl (or 1, if rlknt is 
NIL). Value is (new) rlknt . 



Narking list physically alters it. However, the 
marking is performed undoably. In addition, list 
can always be restored by specifically calling 
rlrestore. 



rlprinl[list] 



prints an expression describing list in the 
single-line format. Does not restore list to its 
uncirclmarked state. list must previously have 
been circlmarked or an error is generated. 



rlprin2[list] 



same as rlprinl , except that the expression 
describing list is printed in the double-line 
format . 



rlrestoreC list] 



physically restores list to its original, unmarked 
state. 



Note that the user can mark and print several structures which together share 
common substructures, e.g. several property lists, by making several calls to 
circlmark , followed by calls to rlprinl or rlprinZ . and finally to rlrestore . 



circlmakerC list] 



list may contain labels and references following 
the convention used by circlprint for printing 
reentrant structures in single line format, e.g. 
(*1* . (1)). circlmaker performs the necessary 
rplaca 's and rplacd 's to make list correspond to 
the indicated structure. Value is (altered) list . 
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Does the work for circlmaker . Uses free variables 
labelst and reflst. labelst is a list of dotted 
pairs of labels and corresponding nodes, reflst 
is a list of nodes containing references to labels 
not yet seen. Circlmaker operates by initializing 
labelst and reflst to NIL, and then calling 
circlroakerl . It generates an error if reflst is 
not NIL when circlmakerl returns. The user can 
call circlmakerl directly to "connect up* several 
structures that share common substructures, e.g. 
several property lists. 
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SECTION 22 
THE PROGRAMMER'S ASSISTANT AND LISPX 



22.1 Introduction 

This chapter describes one of the newer additions to INTERLISP: the 
programmer's assistant. The central idea of the programmer's assistant is that 
the user, rather than talking to a passive system which merely responds to each 
input and waits for the next, is instead addressing an active intermediary, 
namely his assistant. Normally, the assistant is invisible to the user, and 
simply carries out the user's requests. However, since the assistant remembers 
what the user has told him, the user can instruct him to repeat a particular 
operation or sequence of operations, with possible modifications, or to undo 
the effect of certain specified operations. Like DWIM, the programmer's 
assistant is not implemented as a single function or group of functions, but is 
instead dispersed throughout much of INTERLISP.^ Like DWIM, the programmer's 
assistant embodies a philosophy and approach to system design whose ultimate 
goal is to construct a programming environment which would "cooperate" with the 
user in the development of his programs, and free him to concentrate more fully 
on the conceptual difficulties and creative aspects of the problem he is trying 
to solve. 



The programmer's assistant was designed and implemented by W. Teitelroan. 
It is discussed in [Tei4]. 

Some of the features of the programmer's assistant have been described 
elsewhere, e.g. the UNDO command in the editor, the file package, etc. 
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Example 



The following dialogue, taken from an actual session at the console, gives the 
flavor of the programmer's assistant facility in INTERLISP. The user is about 
to edit a function loadf . which contains several constructs of the form 
(PUTO FN2 (GETO FNl)). The user plans to replace each of these by equivalent 
MOVD expressions. 



-E0ITF(LOADFF] [1] 
= LOADF 
EDIT * 
«PP 

[LAMBDA (X Y) 
[COND 

((NULL (GETD (QUOTE READSAVE))) 
(PUTD (QUOTE READSAVE) 

(GETD (QUOTE READ] 
(PUTD (QUOTE READ) 

(GETD (QUOTE REED))) 
(NLSETQ (SETQ X (LOAD X Y))) 
(@UTD (QUOTE READ) 

(GETD (QUOTE READSAVE))) 

X] 

*F PUTD (1 MOVD) [2] 
*3 (XTRR 2) [3] 
=XTR 

*0P C4] 

=0 P 

(MOVD (QUOTE READSAVE) (QUOTE READ)) 

«(SW 2 3) [5] 



At [1], the user begins to edit loadf At [2] the user finds PUTO and replaces 
it by MOVD. He then shifts context to the third subexpression, 13 J, extracts 
its second subexpression, and ascends one level [4] to print and result. The 
user now switches the second and third subexpression [5], thereby completing 



We prefer to consider the programmer's assistant as the moving force behind 
this type of spelling correction (even though the program that does the 
work is part of the DWIM package). Whereas correcting @PRINT to PRINT, or 
XTRR to XTR does not require any information about what this user is doing, 
correcting LOADFF to LOADF clearly required noticing when this user defined 
loadf. 
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the operation for this PUTD. Note that up to this point, the user has not 
directly addressed the assistant. ^ The user now requests that the assistant 
print out the operations that the user has performed, [6], and the user then 
instructs the assistant to REDO FROM f, [7], meaning repeat the entire sequence 
of operations 15 through 20. The user then prints the current expression, and 
observes that the second PUTD has now been successfully transformed. 



15. «F PUTD 

16. *(1 MOVD) 

17. «3 

18. *(XTR 2) 

19. *0 

20. «(SW 2 3) 

*RE0O FROM F [7] 



The user now asks the assistant to replay the last three steps to him, [8]. 
Note that the entire REDO FROM F operation is now grouped together as a single 
unit, [9], since it corresponded to a single user request. Therefore, the user 
can instruct the assistant to carry out the same operation again by simply 
saying REDO. This time a problem is encountered [10], so the user asks the 
assistant what it was trying to do [11]. 

*?? FROM -3 [8] 

19. *0 

20. *(SW 2 3) 

21. REDO FROM F [9] 



*F PUTD 
*(1 MOVD) 
«3 

*(XTR 2) 
«0 

*(SW 2 3) 



«?? FROM F 



[6] 



*P 

(MOVD (QUOTE REED) (QUOTE READ)) 



*REDO 



PUTD ? 



[10] 



«?? -1 



[11] 



22. REDO 
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*F PUTD 
•(1 MOVD) 
*3 

«(XTR 2) 
*0 



The user then realizes the problem is that the third PUTD is misspelled in the 
definition of LOADF (see page 22.2). He therefore instructs the assistant to 
USE @UTO FOR PUTD, [i2]» and the operation now concludes successfully. 



*USE @UTD FOR PUTD [12] 
*P 

(MOVD (QUOTE READSAVE) (QUOTE READ)) 
«t pp 

[LAMBDA (X Y) 

[COND 

((NULL (GETD (QUOTE READSAVE))) 
(MOVD (QUOTE READ) 

(QUOTE READSAVE] 
(MOVD (QUOTE REED) 

(QUOTE READ)) 
(NLSETQ (SETQ X (LOAD X Y))) 
(MOVD (QUOTE READSAVE) 
(QUOTE READ)) 

X] 

*0K 
LOADF 



An important point to note here is that while the user could have defined a 
macro to execute this operation, the operation is sufficiently complicated that 
he would want to try out the individual steps before attempting to combine 
them. At this point, he would already have executed the operation once. Then 
he would have to type in the steps again to define them as a macro, at which 
point the operation would only be repeated once more before failing. Then the 
user would have to repair the macro, or else change @UTD to PUTD by hand so 
that his macro would work correctly. It is far more natural to decide after 
trying a series of operations whether or not one wants them repeated or 
forgotten. In addition, frequently the user will think that the operation(s) 
in question will never need be repeated, and only discover afterwards that he 
is mistaken, as occurs when the operation was Incorrect, but salvageable: 
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(LAMBDA (STR FLGCQ VRB) ««COMMENT** (PROG & & LPl & LP2 & &)) 
«-l -1 P 

(RETURN (COND &)) 

*(-2 ((EQ BB (QUOTE OUT)) BB] [1] 
*P 

(RETURN (& BB) (COND &)) [2] 
*UNDO 

(-2 --) UNDONE 
*2 P 

(COND (EXPANS & & T) ) 

«REDO EQ 

*P 

(COND (& BB) (EXPANS & & T) 



Here the operation was correct, [1], but the context in which it was executed, 
[2], was wrong. 

This example also illustrates one of the most useful functions of the 
programmer's assistant: its UNDO capability. In most systems, if a user 
suspected that a disaster might result from a particular operation, e.g. an 
untested program running wild and chewing up a complex data structure, he would 
prepare for this contingency by saving the state of part or all of his 
environment before attempting the operation. If anything went wrong, he would 
then back up and start over. However, saving/dumping operations are usually 
expensive and time consuming, especially compared to a short computation, and 
are therefore not performed that frequently, and of course there is always the' 
case when diaster strikes as a result of a 'debugged' or at least Innocuous 
operation, as shown in the following example: 



-(MAPC ELTS (FUNCTION (LAMBDA (X) (REMPROP X (QUOTE MORPH] [1] 
NIL 

•-UNDO [2] 
MAPC UNDONE. 

-USE ELEMENTS FOR ELTS [3] 
NIL 



The user types an expression which removes the property MORPH from every member 
of the list ELTS [1], and then realizes that he meant to remove that property 
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only from those members of the list ELEMENTS, a much shorter list. In other 
words, he has deleted a lot of information that he actually wants saved. He 
therefore simply reverses the effect of the MAPC by typing UNDO [2], and then 
does what he intended via the USE command [3]. 

22.2 Overview 

The programmer's assistant facility is built around a memory structure called 
the 'history list.' The history list is a list of the information associated 
with each of the individual 'events' that have occurred in the system, where 
each event corresponds to one user input. For example, (XTR 2) ([3] on page 
22.2) is a single event, while REDO FROM F ([7] on page 22.3} is also a single 
event, although the latter includes executing the operation (XTR 2), as well as 
several others. 

Associated with each event on the history list is its input and its value, plus 
other optional information such as side-effects, formatting information, etc. 
If the event corresponds to a history command, e.g. REDO FROM F, the input 
corresponds to what the user would have had to type to execute the same 
operation(s), although the user's actual input, i.e. the history command, is 
saved in order to clarify the printout of that event ([9] on page 22.3). Note 
that if a history command event combines several events, it will have more than 
one value: 



For various reasons, there are two history lists: one for the editor, and 
one for lispx , which processes inputs to evalqt and break, see page 22.44. 
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-(LOG (ANTILOG 4)) 
4.0 

-USE 4.0 40 400 FOR 4 

4.0 
40.0 

ARG NOT IN RANGE 
400 

-USE -40.0 -4.00007 -19. 

-40.0 

-4.00007 

-19.0 

-USE LOG ANTILOG FOR ANTILOG LOG IN -2 AND -1 

4.0 

40.0 

400.0 

4.00007 

19.0 

-?? 

4. USE LOG ANTILOG FOR ANTILOG LOG IN -2 -1 
-(ANTILOG (LOG 4.0)) 
4.0 

-(ANTILOG (LOG 40)) 
40.0 

-(ANTILOG (LOG 400)) 
400.0 

-(ANTILOG (LOG -40.0)) 
40.0 

-(ANTILOG (LOG -4.00007)) 

4.00007 

-(ANTILOG (LOG -19.0)) 
19.0 

3. USE -40.0 -4.00007 -19.0 
-(LOG (ANTILOG -40.0)) 
-40.0 

-(LOG (ANTILOG -4.00007)) 
-4.00007 

-(LOG (ANTILOG -19.0)) 
-19.0 

2. USE 4.0 40 400 FOR 4 
-(LOG (ANTILOG 4.0)) 
4.0 

(LOG (ANTILOG 40.0) 
40.0 

-(LOG (ANTILOG 400)) 

1. -(LOG (ANTILOG 4)) 
4.0 



As new events occur, existing events are aged, and the oldest event is 
'forgotten.' For efficiency, the storage used to represent the forgotten event 
is cannibalized and reused in the representation of the new event, so the 
history list is actually a ring buffer. The size of this ring buffer is a 
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system parameter called the 'time-slice.' Larger time-slices enable longer 
'memory spans,' but tie up correspondingly greater amounts of storage. Since 
the user seldom needs really 'ancient history,' and a NAME and RETRIEVE 
facility is provided for saving and remembering selected events, a relatively 
small time slice such as 30 events is more than adequate, although some users 
prefer to set the time slice as large as 100 events. 

Events on the history list can be referenced in a number of ways. The output 
on page 22.9 shows a printout of a history list with time-slice 16. The 
numbers printed at the left of the page are the event numbers. More recent 
events have higher numbers; the most recent event is event number 52, the 
oldest and about-to-be-forgotten event is number 37.^ At this point in time, 
the user can reference event number 51, RECONPILE(EOIT), by its event number, 
51; its relative position, -Z (because it occurred two events back from the 
current time), or by a 'description' of its input, e.g. (RECOMPILE (EDIT)), or 
(& (EDIT)), or even Just EDIT. As new events occur, existing events retain 
their absolute event numbers, although their relative positions change. 

Similarly, descriptor references may require more precision to refer to an 
older event. For example, the description RECOMPILE would have sufficed to 
refer to event 51 had event 52, also containing a RECOMPILE, not intervened. 
Event specification will be described in detail later. 



Initially 30 events. The time-slice can be changed with the function 
changes lice , page 22.54. 



When the event number of the current event is 100, the next event will be 
given number 1. (If the time slice is greater than 100, the 'roll-over' 
occurs at the next highest hundred, so that at no time will two events ever 
have the same event number. For example, if the time slice is 150, event 
number 1 follows event number 200.) 
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♦•7? 



52. ... HIST UNDO 

-RECOMPILE(HIST) 

HIST.COM 

*-RECOMPILE(UNDO) 

UND0.COM 
51. *-RECOMPILE(EDIT) 

EDIT.COM 
50. -LOGOUT] 

49. -MAKEFILES] 

(EDIT UNDO HIST) 
48. -EOITFCUNDOLISPX) 

UNDOLISPX 
47. REDO GETO 

-GETD(FIE) 

(LAMBDA (X) (MAPC X (F/L (PRINT X)))) 
46. -UNDO 
FIE 

45. -GETD(FIE) 

(LAMBDA (X) (MAPC X (FUNCTION (LAMBDA (X) (PRINT X))))) 
44. -FIE] 

NIL 

43. -DEFINEQ((FIE (LAMBDA (X) (MAPC X (F/L (PRINT X)))))) 

(FIE) 
42. REDO GETD 

-GETD(FIE) 

(LAMBDA (Y) Y) 
41. -UNDO 

MOVD 
40. REDO GETD 

-GETD(FIE) 

(LAMBDA (X) X) 
39. -MOVD(FOO FIE) 

FIE 

38. -DEFINEQ((FOO (LAMBDA (X) X))) 

(FOO) 
37. -GETD(FIE) 

(LAMBDA (Y) Y) 



The most common interaction with the programmer's assistant occurs at the top 
level evalqt , or in a break, where the user types in expressions for 
evaluation, and sees the values printed out. In this mode, the assistant acts 
much like a standard LISP evalqt , except that before attempting to evaluate an 
input, the assistant first stores it in a new entry on the history list. Thus 
if the operation is aborted or causes an error, the input is still saved and 
available for modification and/or reexecution. The assistant also notes new 
functions and variables to be added to its spelling lists to enable future 
corrections. Then the assistant executes the computation (i.e. evaluates the 
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form or applies the function to its arguments), saves the value in the entry on 
the history list corresponding to the input, and prints the result, followed by 
a prompt character to indicate it is again ready for input. 

If the input typed by the user is recognized as a history command, the 
assistant takes special action. Commands such as UNDO, 77, NAME, and RETRIEVE 
are immediately performed. Commands that involved reexecution of previous 
inputs, e.g. REDO and USE, are achieved by computing the corresponding input 
expression(s) and then unreading them. The effect of this unreading operation 
is to cause the assistant's input routine, lispxread , to act exactly as though 
these expression were typed in by the user. Except for the fact that these 
inputs are not saved on new and separate entries on the history list, but 
associated with the history command that generated them, they are processed 
exactly as though they had been typed. 

The advantage of this implementation is that it makes the programmer's 
assistant a callable facility for other system packages as well as for users 
with their own private executives. For example, break'l accept user inputs, 
recognizes and executes certain break commands and macros, and interprets 
anything else as INTERLISP expressions for evaluation. To interface breakl 
with the programmer's assistant required three small modifications to breakl : 
(1) input was to be obtained via lispxread instead of read ; (2) instead of 
calling eval or apply directly, breakl was to give those inputs it could not 



The function that accepts a user input, saves the input on the history 
list, performs the indicated computation or history command, and prints the 
result, is lispx . llspx is called by evalqt and breakl , and in most cases, 
is synonymous with 'programmer's assistant.' However, for various reasons, 
the editor saves its own inputs on a history list, carries out the 
requests, i.e. edit commands, and even handles undoing independently of 
lispx . The editor only calls lispx to execute a history command, such as 
REDO, USE, etc. Therefore we use the term assistant (loosely) when the 
discussion applies to features shared by evalqt , break and the editor, and 
the term lispx when we are discussing the specific function. 
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interpret to lispx , and (3) any commands or macros handled by breakl , i.e. not 
given to lispx , were to be stored on the history list by breakl by calling the 
function historysave , a part of the assistant package. 

Thus when the user typed in a break command, the command would be stored on the 
history list as a result of (3). If the user typed in an expression for 
evaluation, it would be evaluated as before, with the expression and its value 
both saved on the history list as a result of (2). Now if the user entered a 
break and typed three inputs: EVAL, (CAR f VALUE), and OK, at the next break, he 
could achieve the same effect by typing REDO FROM EVAL. This would cause the 
assistant to unread the three expressions EVAL, (CAR ! VALUE), and OK. Because 
of (1), the next 'input' seen by breakl would then be EVAL, which break 1 would 
interpret. Next would come (CAR ! VALUE), which would be given to lispx to 
evaluate, and then would come OK, which breakl would again process. Thus, by 
virtue of unreading^ history operations will work even for those inputs not 
interpretable by lispx , in this case, EVAL and OK. 

The net effect of this implementation of the programmer's assistant is to 
provide a facility which is easily inserted at many levels, and embodies a 
consistent set of commands and conventions for talking about past events. This 
gives the user the subjective feeling that a single agent is watching 
everything he does and says, and is always available to help. 

22.3 Event Specification 

All history commands use the same conventions and syntax for indicating which 
event or events on the history list the command refers to, even though 
different commands may be concerned with different aspects of the corresponding 
event(s), e.g. side-effects, value, input, etc. Therefore, before discussing 
the various history commands in the next section, this section describes the 
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types of event specifications currently implemented. All examples refer to the 
history list on page 22.9. 

An event address identifies one event on the history list. It consists of a 
sequence of 'commands' for moving an imaginary cursor up or down the history 
list, much in the manner of the arguments to the 9 command in break (see 
Section 15). The event identified is the one 'under' the imaginary cursor when 
there are no more commands. (If any command fails, an error is generated and 
the history command is aborted.) 



The commands are interpreted as follows: 



n (n > i) move forward n events, i.e. in direction of 

increasing event number. If given as the first 
'command,' n specifies the event with event number 
n. " 

n (n < -1) move backward -n events. 

«-atom search backward for an event whose function 

matches atom (i.e. for apply format only), e.g. 
whereas FIE would refer to event 47, •-FIE would 
refer to event 44. Similarly, E0$ would specify 
event 51, whereas «-E0$ event 48. 

pat^ search backward for an event whose input contains 

an expression that matches pat as described in 
Section 9. 

«- next search is to go forward instead of backward, 

(if given as the first 'command', next search 
begins with last, i.e. oldest, event on history 
list), e.g. *• LAMBDA refers to event 38; 
MAKEFILES - RECOMPILE refers to event 51. 

F next object is to be searched for, regardless of 

what it is, e.g. F -2 looks for an event 
containing a -2. 

= next search is to look at values, instead of 



i.e. EDalt-mode. 

p 

i.e. anything else except for ■, and which are interpreted as 
described above. 
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inputs, e.g. =UNDO refers to event 49; 45 - FIE 
refers to event 43; = LAMBDA refers to event 37. 



specifies the event last located. 

Note: each search skips the current event, i.e. each command always moves the 
cursor. For example, if FOO refers to event n, FOO FIE will refer to some 
event before event n, even if there is a FIE in event n. 

An event specification specifies, one or more events: 



FROM #1 THRU #2 
#1 THRU #2 



the sequence of events from the 
event with address #1 through event with address 
*Z/^ e.g. FROM GETD THRU 49 specifies events 47, 
48, and 49. #1 can be more recent than #2, e.g. 
FROM 49 THRU GETP specifies events 49, 48, and 47 
(note reversal of order). 



FROM #1 TO #2 
#1 TO #2 



Same as THRU but does not include event #2 



FROM #1 



Same as FROM #1 THRU -1, e.g. FROM 49 specifies 
events 49, 50, 51, and 52. 



THRU #2 



Same as FROM -1 THRU #2, e.g. THRU 49 specifies 
events 52, 51, 50, and 49. Note reversal of 
order. 



TO 



Same as FROM -1 TO #2. 



#1 AND #2 AND ... AND #n i.e. a sequence of event addresses separated by 

AND's, e.g. FROM 47 TO LOGOUT would be equivalent 
to 47 AND 48 AND MAKEFILES. 

empty i.e. nothing specified, same as -1, unless.. last 

event was an UNDO, in which case same as -2. 



10 
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i.e. the symbol #1 corresponds to all words between FROM and THRU in the 
event specification, and #2 to all words from THRU to the end of the event 
specification. For example, in FROM FOO 2 THRU FIE -1, #1 is (FOO 2), and 
#2 is (FIE -1). 

For example, if the user types (NCONC FOO FIE), he can then type UNDO, 
followed by USE NCONCl. 
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© atom refers to the events named by atom, via the NAME 

command, page 22.25 e.g., if the user names a 
particular event or events FOO, © FOO specifies 
those events. 

00 ^ ^ is an event specification and interpreted as 

above, but with respect to the archived history 
list, as specified on page ZZ,Z7. 



ZZ,4 History Commands 



All history commands can be input as either lists, or as lines (see read line 
Section 14, and also page 22.47). 

^ is used to denote an event specification. Unless specified otherwise , /! 
omitted is the same as i ft, e.g. REDO and REDO -i are the same. 



REDO € 

USE vars FOR args IN i 



USE vars^ FOR args^ AND 



redoes the event or events specified by e.g* 
REDO FROM -3 redoes the last three events. 

substitutes vars for args in €, and redoes the 

reisult, e.g. 

USE LOG ANTIL06 FOR ANTILOG LOG IN -2 AND -1. 
Substitution is done by esubst . Section 9, and is 
carried out as described below. 

AND vars FOR args IN i 
More general form of USE command. See description 
of substitution algorithm below. 



Every USE command involves three pieces of information: the variables to be 
substituted, the arguments to be substituted for, and an event specification. 



which defines the expression (input) in which the substitution takes place. 
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If args are omitted, i.e. the form of the command is USE vars IN iJ, or just USE 
vars (which is equivalent to USE vars IN -1), and the >event referred to was 
itself a USE command, the argument's and expression substituted into are the 
same as for the indicated USE command. In effect, this USE command is thus a 



The USE command is parsed by a small finite state parser to distinguish the 
variables and arguments. For example, USE FOR FOR AND AND AND FOR FOR will 
be parsed correctly. 



22.14 



continuation of the previous USE command. For example, on page ZZ,7, when the 
user types (LOG (ANTILOG 4)), followed by USE 4.0 40 400 FOR 4, followed by 
USE -40.0 -4.00007 -19., the latter command is equivalent to 
USE -40.0 -4.00007 -19. FOR 4 IN -2. 

args are omitted and the event referred to was not a USE command, 
substitution is for the operator in that command, i.e. if a lispx input, the 
name of the function, if an edit command, the name of the command. For example 
ARGLIST(FF) followed by USE CALLS is equivalent to USE CALLS FOR ARGLIST. 

If € is omitted, but args are specified, the first member of args is used for 
^, e.g. USE PUTO FOR eUTD is equivalent to USE PUTO FOR 9UT0 IN F eUTD.^^ 

If the USE command has the same number of expressions as arguments, the 
substitution procedure is straightforward,^^ i.e. USE X Y FOR U V means 
substitute X for U and Y for V, and is equivalent to USE X FOR U AND Y FOR V. 
However, the USE command also permits distributive substitutions, i.e. 
substituting several expressions for the same argument. For example, 
USE ABC FOR X means first substitute A for X then substitute B for X (in a 
new copy of the expression), then substitute C for X. The effect is the same 
as three separate USE commands. Similarly, USE ABC FOR D AND X Y Z FOR W is 
equivalent to USE A FOR D AND X FOR W, followed by USE B FOR D AND Y FOR W, 
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t4 



The F is inserted to handle correctly the case where the first member of 
args is a number, e.g. USE 4.0 4.0 400 FOR 4. Obviously the user means find 
the event containing a 4 and perform the indicated substitutions, whereas 
USE 4.0 40 400 FOR 4 IN 4 would mean perform the substitutions in event 
number 4. 

Except when one of the arguments and one of the variables are the same, 
e.g. USE X Y FOR Y X, or USE X FOR Y AND Y FOR X. This situation is noticed 
when parsing the command, and^handled correctly? 
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followed by USE C FOR D AND Z FOR W. USE A B C FOR D AND X FOR Y^^ also 

corresponds to three substitions, the first with A for 0 and X for Y, the 

second with B for 0, and X for Y, and the third with C for D, and again X for 

Y. However, USE ABC FOR D AND X Y FOR Z is ambiguous and will cause an 

error. Essentially, the USE coinunand operates by proceeding from left to right 

handling each 'AND' separately. Whenever the number of expressions exceeds the 
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number of expressions available,, the expressions multiply. 



FIX € puts the user in the editor looking at a copy of 

the input(s) for Whenever the user exits via, 
OK, the result is unread and reexecuted exactly as 
with REDO. 



FIX is provided for those cases when the modifications to the input(s) are not 
of the type that can be specified by USE, i.e. not substitutions. For example: 



«-(DEFINEQ FOO (LAMBDA (X) (FIXSPELL SPELLINGS2 X 70] 

INCORRECT DEFINING FORM 
FOO 

-FIX 
EDIT 
«P 

(DEFINEO FOO (LAMBDA & &)) 

*(LI 2) 

OK 

(FOO) 



The user can also specify the edit comroand(s) to lispx , by typing - followed by 
the command(s) after the event specification, e.g. FIX - (LI 2). In this case, 
the editor will not type EDIT, or wait for an OK after executing the commands. 



or USE X FOR Y AND A 6 C FOR D. 



Thus USE A B C D FOR E F means substitute A for E at the same time as 
substituting B for F, then in another copy of the indicated expression, 
substitute C for E and D for F. Note that this is also equivalent to 
USE A C FOR E AND B D FOR F. 
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Implementation of REDO, USE, and FIX 



The input portion of an event is represented internally on the history list 
simply as a linear sequence of the expressions which were read. For example, 
an input in apply format is a list consisting of two expressions, an an input 
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pval format is a list of Just one expression. Thus if the user wishes to 
convert an input in apply format to eval format, he simply moves the function 
name inside of the argument list: 



♦-MAPC(FOOFNS (F/L (AND (EXPRP X) (PRINT X] 

NIL 

♦-EXPRP(FOOl) 
T 

-FIX MAPC 

EDIT 

«rp 

(MAPC (FOOFNS &)) 
*(B0 2) 
*(LI 1) 
*P 

((MAPC FOOFNS &)) 
OK 

FOOl 
FIE2 
FUM 
NIL 



By simply converting the input from two expressions to one expression, the 
desired effect, that of mapping down the list that was the value of foofns , was 
achieved. 



REDO, USE, and FIX all operate by obtaining the input portion of the 
corresponding event, processing the input (except for REDO), and then storing 



For inputs in eval format, i.e. single expressions, FIX calls the editor so 
that the current expression is that input, rather than the list consisting 
of that input - see the example on the preceding page. However, the entire 
list is actually being edited. Thus if the user typed t p in that example, 
he would see ((DEFINEQ FOO &)). 
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it on the history list as the input portion of a new event. The history 
command completes operating by simply unreading the input. Vfhen the input is 
subsequently 'reread', the event which already contains the input will be 
retrieved and used for recording the value of the operation, saving side- 
effects, etc., instead of creating a new event. Otherwise the input is treated 
exactly the same as if it had been typed in directly. 

If t specifies more than one event, the inputs for the corresponding events are 
simply concatenated into a linear sequence, with special markers representing 
carriage returns inserted between each input to indicate where new lines 
start. The result of this concatenation is then treated as the input referred 
to by For example, when the user typed REDO FROM F ([7] on page 22.3) the 
inputs for the corresponding six events were concatenated to produce 
(F PUTO #0 (1 MOVD) #0 3 #0 (XTR 2) #0 0 #0 (SW 2 3)). Similarly, if the user 
had typed USE ^UTD FOR PUTD IN 15 THRU 20, (F PUTO #0 (1 MOVD) #0 3 #0 (XTR 2) 
#0 0 #0 (SW 2 3)) would have been constructed, and then 9UT0 substituted for 
PUTD throughout it. 

The same convention is used for representing multiple inputs when a USE command 
involves sequential substitutions. For example, if the user types GETD(FOO) 
and then USE FIE FUN FOR FOO, the input sequence that will be constructed is 
(GETO (FIE) #0 GETD (FUM)), which is the result of substituting FIE for FOO in 
(GETD (FOO)) concatenated with the result of substituting FUN for FOO in 
(GETD (FOO)). 

Once such a multiple input is constructed, it is treated exactly the same as a 
single input, i.e. the input sequence is recorded in a new event, and then 



The value of (VAG 0) is currently used to represent a carriage return on 
the grounds that it cannot be typed in by the user, and thus cannot cause 

ambiguities. 
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unread, exactly as described above. When the Inputs are 'reread,' the 'pseudo- 
carriage-returns' are treated by lispxread and readline exactly as real 
carriage returns, i.e. they serve to distinguish between apply and eval formats 
on inputs to lispx , and to delimit line commands to the editor. Note that once 
this multiple input has been entered as the input portion of a new event, that 
event can be treated exactly the same as one resulting from type in. In other 
words, no special checlcs have to be made when referencing an event, to see if 
it is simple or multiple. Thus» when the user types REDO following 
REDO FROM F, ([10] page 22.3) REDO does not even notice that the input 
retrieved from the previous event is (F PUTD #0 ... (SW 2 3)) i.e. a multiple 
input, it simply records this input and unreads it. Similarly, when the user 
then types USE @UTD FOR PUTD on this multiple input, the USE command simply 
carries out the substitution, and the result is the same as though the user had 
typed USE @UTD FOR PUTD IN 15 THRU 20. 

In sum. this implementation permits € to refer to a single simple event, or to 
several events, or to a single event originally constructed from several events 
(which may themselves have been multiple input events, etc.) without having to 
treat each case separately. 

History Commands Applied to History Commands 

Since history commands themselves do not appear in the input portion of events 
(although they are stored elsewhere in the event), they do not interfere with 
or affect the searching operations of event specifications. In effect* history 
commands are invisible to event specifications. As a result, history commands 
themselves cannot be recovered for execution in the normal way. For example. 



With the exception described below under "History Commands that Fail". 
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if the user types USE A B C FOR 0 and follows this with USE E FOR 0, he will 
not produce the effect of USE ABC FOR E (but instead will simply cause E to 
be substituted for 0 in the last event containing a 0). To produce this 
effect, i.e. USE A B C FOR E. the user should type USE D FOR E IN USE. The 
appearance of the word REDO, USE or FIX in an event address specifies a search 
for the corresponding history command. (For example, the user can also type 
UNDO REDO.) It also specifies that the text of the history command itself be 
treated as though it were the input. However, the user must remember that the 
context in lohich a history command is reexecuted is' that of the current 
history, not the original context. For example, if the user types 
USE FOO FOR FIE IN -1, and then later types REDO USE, the -1 will refer to the 
event before the REDO, not before the USE. Similarly, if the user types 
REDO REDO followed by REDO REDO, he would cause an infinite loop, except for 
the fact that a special check detects this type of situation. 

History Commands that Fail 

The one exception to the statement that 'history commands are invisible to 
event specifications' occurs when a history command fails to produce any input. 
For example, suppose the user types USE LOG FOR ANTILOG AND ANTILOG FOR LOGG, 
causing lisp x to respond LOGG ?. Since the USE command did not produce any 
input, the user can repair it by typing USE LOG FOR LOGG (i.e. does not have to 
specify IN USE). This latter USE command will invoke a search for LOGG, which 
will find the bad USE command, lispx then performs the indicated substitution, 
and unreads USE LOG FOR ANTILOG AND ANTILOG FOR LOG. In turn, this USE command 
invokes a search for ANTILOG, which, because it was not typed in but reread^ 
ignores the bad USE command which was found by the earlier search for LOGG, and 
which is still on the history list. In other words, history commands that fail 
to produce input are visible to searches arising from event specifications 
typed in by the user, but not to secondary event specifications . 
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In addition, if the most recent event is a history command Which failed to 
produce input, a secondary event specification will effectively back up the 
history list one event so that relative event numbers for that event 
specification will not count the bad history command. For example, suppose the 
user types USE LOG FOR ANT I LOG AND ANTILOG FOR LOGG IN -2 AND -1, and after 
lispx types LOGG ?, the user types USE LOG FOR LOGG. He thus causes the command 
USE LOG FOR ANTILOG AND ANTILOG FOR LOG IN -2 AND -1 to be constructed and 
unread. In the normal case, -1 would refer to the last event, i.e. the 'bad' 
USE command, and -2 to the event before it. However, in this case, -1 refers 
to the event before the bad USE command, and the -Z to the event before that. 
In short, the caveat that "the user must remember that the context in which a 
history command is reexecuted is that of the current history, not the original 
context" does not apply if the correction is performed immediately. 

More History Commands 

RETRY ^ similar to REDO except sets helpclock so that any 

errors that occur while executing € will cause 
breaks. 

... vars similar to USE except substitutes for the (first) 

operand. 

For example, EXPRP(FOO) followed by . . . FIE FUM is equivalent to 
USE FIE FUM FOR FOO. See also event 52 on page 22.9. 

?7 € prints history list. If <! is omitted, 7? prints 

the entire history list, beginning with most 
recent events. Otherwise 77 prints only those 
events specified in t (and in the order 
specified), e.g. 77 -1, 77 10 THRU 15, etc. 

77 commands are not entered on the history list, and so do not affect relative 
event numbers. In other words, an event specification of -1 typed following a 
77 command will refer to the event immediately preceding the 77 command. 
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7? will print the history conunandp if any, associated with each event as shown 

at [9] on page 22.3 and page 22.7. Note that these history commands are not 

20 

preceded by prompt characters* indicating they are not stored as input. 



77 prints multiple input events under one event number (see page 22.7). 

Since events are initially stored on the history list with their value field 
equal to bell (control-G), if an operation fails to complete for any reason, 
e.g. causes an error, is aborted, etc., its 'value' will be bell. This is the 
explanation for the blank line in event 2, page 22.7, and event 50, page 22.9* 

7? is implemented via the function printhistory , page 22.60, which can also be 
called directly by the user. 

« « n ' 



UNDO d undoes the side effects of the specified events. 

For each event undone, UNDO prints a message: e.g. 
RPLACA UNDONE, REDO UNDONE etc. If nothing is 
undone because nothing was saved, UNDO types 
NOTHING SAVED. If nothing was undone because the 
event(s) were already undone, UNDO types 
ALREADY UNDONE. If € is empty, UNDO searches back 
for the last event that contained side effects, 
was not undone, and itself was not an UNDO 



REDO, RETRY, USE, and FIX commands, i.e. those commands that reexecute 

previous events, are not stored as inputs, because the input portion for 
these events are the expressions to be 'reread*. The history commands 
UNDO, NAME. RETRIEVE, BEFORE, and AFTER are recorded as inputs, and 7? 
prints them exactly as they were typed. 
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command. 
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UNDO : Xj . . . 



Each X. refers to a message printed by DWIM in the 
evGnt(s) specified by i. The side effects of the 
corresponding DWIN corrections, and only those 
side effects, are undone. 



For example, if the message PRINTT [IN FOO] -> PRINT were printed, 
UNDO : PRINTT or UNDO : PRINT would undo the correct ion. 



$ is a special form of the USE command for conveniently specifying character 
substitutions. In addition, it has a number of useful default options in 
connection with events that involve errors. 



For example, the user types MOVD(FOO FOOSAVE T), he can then type $ FIE FOR FOO 
to perform MOV0(FIE FIESAVE T). Note that USE FIE FOR FOO would perform 
MOVD(FIE FOOSAVE T). 



Note that the user can undo UNDO commands themselves by specifying the 
corresponding event address, e.g. UNDO -3 or UNDO UNDO. 



UNDOing events in the reverse order from which they were executed is 
guaranteed to restore all pointers correctly, e.g. to undo all effects of 
last five events, perform UNDO THRU -5, not UNDO FROM -5. Undoing out of 
order may have Unforseen effects if the operations are dependent . For 
example, if the user performed (NCONCl FOO FIE), followed by 
(NCONCl FOO FUM), and then undoes the (NCONCl FOO FIE), he will also have 
undone the (NCONCl FOO FUM). If he then undoes the (NCONCl FOO FUM), he 
will cause the FIE to reappear, by virtue of restoring FOO to its state 
before the execution of (NCONCl FOO FUM). For more details, see page 
22.42. 



Some portions of the messages printed by DWIM are strings, e.g. the message 
FOO UNSAVED is printed by printing FOO and then " UNSAVED". Therefore, if 
the user types UNDO : UNSAVED, the DWIN correction will not be found. He 
should Instead type UNDO : FOO or UNDO : SUNSAVEDS (alt-modeUNSAVEOalt- 
mode, see R command in editor, section 9). 



« 



S X FOR y 



equivalent to USE $x$ FOR Sy$ 



22.23 



An abbreviated forin of S is available: 

$ y X same as $ x FOR y, i.e. y's are changed to x's. 

can also be written as S y TO x, S y s x, or 
S y -> X. 

$ does event location the same as the USE conunand, i.e. if IN is not 
Specif ied» it searches for ^. 

After $ finds the event* it loolcs to see if an error was involved in that 
event » and if the indicated character substitution can be performed in the 
offender. If so, S assumes the substitution refers to the offender, performs 
the substitution, and then substitutes the result for the offender throughout. 
For example. the user types (PRETTYOEF FOOFNS 'FOO FOOVARS) causing a 
U.B.A. FOOOVARS error message. The user can now type S 00 0, which will change 
FOOOVARS to FOOVARS, but not change FOOFNS or FOO. 

If an error did occur in the specified event, the user can also omit specifying 
in which case the offender is used. Thus, the user could have corrected the 
above example by simply typing S FOOVARS. Similarly, if the user types 
LOAD(PRSTRUC PROP), causing the error FILE NOT FOUND PRSTRUC, he can request 
the file to be loaded from LISP'S directory by simply typing S <LISP>S. Since 
esubst is used for substituting, this is equivalent to performing 
(R PRSTRUC <LISP>S) on the event, and therefore replaces PRSTRUC by 
<LISP>PRSTRUC (see Section 9). Note also the usefulness of S *$, meaning: put 
a ' in front of the offender. 



However, unlike USE, $ can only he used to specify one substitution at a 
time . 

Whenever an error occurs, the object of the error message, called the 
offender, is automatically saved on that event's entry in the history list, 
under the property ERROR. 
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$ also works for events in the editor. For example, if the user types 
(MOVE CONO 33 Z TO BEFORE HERE), and editor types 33 7, the user can type $ 3, 
causing 3 to be substituted for 33 in the HOVE command. 

Finally, the user can omit both x and ^. This specifies that two alt-modes be 
packed onto the end of the offender, and the result substituted throughout the 
specified event. For example, suppose the user types to the editor 
(MOVE 3 2 TO AFTER CONGO 1), and gets the error message CONDD ?. because the 
find command failed to find CONDD. $ will cause the edit command 
(MOVE 3 2 TO AFTER CONDDSS 1) to be executed, which will search for an atom 
that is "close" to CONDD in the sense used by the spelling corrector (see 
pattern type 6b, Section 9).^^ 

Note that $ never searches for an error. Thus, if the user types 
LOAD(PRSTRUC PROP) causing a FILE NOT FOUND error, types CLOSEALLO, and then 
types S <LISP>S, lispx will complain that there is no error in CLOSEALLO. In 
this case, the user would have to type S <LISP>S IN LOAD, or 
$ PRS <LISP>PRS (which would cause a search for PRS). 

Note also that $ operates on input » not on programs. If the user types F00(), 
and within the call to FOO gets a U.D.F. CONDD error, he cannot repair this by 
S COND. lispx will type CONDD NOT FOUND IN F00(). 

« « « 

NAME atom ^ saves the event(s) (including side effects) 

specified by € on the property list of atom (under 
the property HISTORY) e.g. NAME FOO 10 THRU 15. 
NAME commands are undoable. 



The same effect could be achieved by S COND, which specifies substituting 
COND for CONDD, but not by S CONDD$$, since the latter is equivalent to 
performing (R CONDD CONDDSS) on the event, which would result in 
CONOOCONDDCONDD being substituted for CONDD (as described in Section 9). 
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RETRIEVE atom Retrieves and reenters on the history list the 

events named by atom . Causes an error if atom was 
not named by a NAME command. 

For example, if the user performs NAME FOO 10 THRU 15, and at some time later 
types RETRIEVE FOO, 6 new events will be recorded on the history list (whether 
or not the corresponding events have been forgotten yet). Note that RETRIEVE 
does not reexecute the events, it simply retrieves them. The user can then 
REDO, UNDO, FIX, etc. any or all of these events. Note that the user can 
combine the effects of a RETRIEVE and a subsequent history command in a single 
operation by using an event specification of the form 9 atom, as described on 
page ZZ. 14, e.g. REDO @ FOO is equivalent to RETRIEVE FOO, followed by an 
appropriate REDO.^^ Note that UNDO 9 FOO and 7? 9 FOO are permitted. 

BEFORE atom undoes the effects of the events named by atom. 

AFTER atom undoes a BEFORE atom. 

BEFORE/AFTER provide a convenient way of flipping back: and forth between two 
states, namely that state before a specified event or events were executed, and 
that state after execution. For example, if the user has a complex data 
structure which he wants to be able to interrogate before and after certain 
modifications, he can execute the modifications, name the corresponding events 
with the NAME command, and then can turn these modifications off and on via 
BEFORE or AFTER commands .^^ Both BEFORE and AFTER are NOPs if the atom was 



Actually, REDO 9 FOO is bettor than RETRIEVE followed by REDO since in the 
latter case, the corresponding events would be entered on the history list 
twice, once for the RETRIEVE and once for the REDO. 



The alternative to BEFORE/AFTER for repeated switching back and forth 
involves UNDO, UNDO of the UNDO, UNDO of that etc. At each stage, the user 
would have to locate the correct event to undo, and furthermore would run 
the risk of that event being 'forgotten' if he did not switch at least once 
per time-slice. 
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already in the corresponding state; both generate errors if atom was not named 
by a NAME command. 

Note: since UNDO, NAME, RETRIEVE » BEFORE, and AFTER are recorded as inputs they 
can be referenced by REDO, USE, etc. in the normal way. However, the user 
must again remember that the context in which the command is reexecuted is 
different than the original context. For example, if the user types 
NAME FOO DEFINEQ THRU COMPILE, then types ... FIE. the input that will be 
reread will be NAME FIE DEFINEQ THRU COMPILE as was intended, but both DEFINEQ 
and COMPILE, will refer to the most recent event containing those atoms, namely 
the event consisting of NAME FOO DEFINEQ THRU COMPILE! 

ARCHIVE ^ records the events specified by ^ on a permanent 

history list. This history list can be referenced 
by preceding a standard event specification with 
e.g. 77 @@ prints the archived history list, 
REDO 00-1 will recover the corresponding event 
from the archived history list and redo it, etc. 

The user can also provide for automatic archiving of selected events by 
appropriately defining archivefn , as described on page 22.33. 

FORGET it permanently erases the record of the side effects 

for the events specified by i. If ^ is omitted, 
forgets side effects for entire history list. 

FORGET is provided for users with space problems. For example, if the user has 
just performed set s, rplaca s, rplacd s, putd , remprop s, etc. to release 
storage, the old pointers would not be garbage collected until the 
corresponding events age sufficiently to drop off the end of the history list 
and be forgotten. FORGET can be used to force immediate forgetting (of the 
side-effects only). FORGET is not undoable (obviously). 
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22.5 Miscellaneous Features and Commands 



TYPE-AHEAD is a command that allows the user to type-ahead an 

indefinite number of inputs. 

The assistant responds to TYPE-AHEAD with a prompt character of >. The user 
can now type in an indefinite number of lines of input, under errorset 
protection. The input lines are saved and unread when the user exits the type- 
ahead loop with the command SGO (alt-modeGO) . While in the type-ahead loop, 77 
can be used to print the type-ahead, FIX to edit the type-ahead, and SQ to 
erase the last input (may be used repeatedly). For example: 
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♦-TYPE-AHEAD 

>SYSOUT(TEM) 

>MAKEFILE(EOIT) 

>BRECOMPILE((E0IT WEOIT)) 

>F 

>$Q 

\\F 
>$Q 

WBRECOMPILE 
>LOAD(WEDIT PROP) 
>BRECOMPILE((EDIT WEOIT)) 

>F 

>MAKEFILE(BREAK) 

>LISTFILES(EOIT BREAK) 

>SVSOUT(CURRENT) 

>LOGOUT] 

>?? 

>SYSOUT(TEM) 
>MAKEFILE(EOIT) 
>LOAD(WE0IT PROP) 
>BRECOMPILE( (EDIT WEOIT)) . 
>F 

>MAKEFILE(BREAK) 
>LISTFILES(EOIT BREAK) 
>SYSOUT(CURRENT) 
>LOGOUT] 

>FIX 
EDIT 

*(R BRECOMPILE BCOMPL) 
*P 

((LOGOUT) (SYSOUT &) (LISTFILES &) (MAKEFILE &) (F) (BCOMPL &) 

(LOAD &) (MAKEFILE &) (SYSOUT &)) 

*( DELETE LOAD) 

«0K 

>SGO 



The TYPE-AHEAD command may be aborted by SSTOP; control-E simply aborts the 
current line of input. 



Note that type-ahead can be addressed to the compiler, since it uses 
lispxread for input. Type-ahead can also be directed to the editor, but 
type-ahead to the editor and to lispx cannot be intermixed. 
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SBUFS (alt-modeBUFS) 



is a command for recovering the input buffers. 



Whenever an error occurs in executing a lispx input or edit command, or a 
control-£ or control-0 is typed, the input buffers are saved and cleared. The 
SBUFS command is used to restore the input buffers, i.e. its effect is exactly 
the same as though the user had retyped what was 'lost.' For example: 

(SETQ X (COND ((NULL Z) (CONS (user typed control-E) 

*P 

(CONO (& &) (T &)) 
*2 

*$BUFS 

(-2 (SETQ X (COND ((NULL Z) (CONS 
and user can now finish typing the (-2 ..) command. 

Note: the type-ahead does not have to have been seen by INTERLISP, i.e., 
echoed, since the system buffer is also saved. 

Input buffers are not saved on the history list, but on a free variable. Thus, 
only the contents of the input buffer as of the last clearbuf can ever be 
recovered. However, input buffers cleared at evalqt are saved independently 
from those cleared by break or the editor. The procedure followed when the 
user types SBUFS is to recover first from the local buffer, otherwise from the 
top level buffer. *^ Thus the user can lose input in the editor, go back to 
evalqt . lose input there, then go back into the editor, recover the editor's 



The local buffer is stored on lispxbufs ; the top level buffer on 
toplispxhufs. The forms of both buffers are (CONS (LINBUF) (SYSBUF)) (see 
Section 14). Recovery of a buffer is destructive, i.e. SBUFS sets the 
corresponding variable to NIL. If the user types SBUFS when both lispxbufs 
and toplispxhufs are NIL, the message NOTHING SAVED is typed, and an error 
generated. 
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buffer, etc. Furthermore, a buffer cleared at the top can be recovered in a 
break, and vice versa. 

ft ft ft 

The following four commands, 00, IF, !E, and !N, are only recognized in the 
editor: 

00 com allows the user to supply the command name when it 

was omitted. (USE is used when a command name is 
incorrect) . 

For example, suppose the user wants to perform 

(-2 (SETO X (LIST Y Z))) but instead types just (SETQ X (LIST V Z) ) . The 
editor will type SETQ ?, whereupon the user can type DO -2. The effect is the 
same as though the user had typed FIX, followed by (LI 1), (-1 -2), and OK, 
i.e. the command (-2 (SETQ X (LIST Y Z)}} is executed. DO also works if the 
last command is a line command. 

!F same as DO F. 



In the case of !F, the previous command is always treated as though it were a 
line command, e.g. if the user types (SETQ X &) and then !F, the effect is the 
same as though he had typed F (SETQ X &), not (F (SETQ X &)). 

!E same as DO E. Note !E works correctly for 

'commands' typed in eval or apply format. 

!N same as DO N. 
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control-U when typed in at any point during an input being 

read by lispxread , permits the user to edit the 
input before it is returned to the calling 
function. 

This feature is useful for correcting mistakes noticed in typing before the 
input is executed, instead of waiting till after execution and then performing 
an UNDO and a FIX. For example, if the user types 
(OEFINEQ (FOO (LAMBDA (X) (FIXSPELL X and at that point notices the missing 
left parenthesis, instead of completing the input and allowing the error to 
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occur, and then fixing the input, he can simply type control-U, finish typing 
normally, whereupon the editor is called on (FOO (LAMBDA (X) (FIXSPELL X ], 
which the user can then repair, e.g. by typing (LI 1). If the user exits from 
the editor via OK, the (corrected) expression will be returned to whoever 

op 

called lispxread exactly as though it had been typed. If the user exits via 
STOP, the expression is returned so that it can be stored on the history list. 
However it will not be executed. In other words, the effect is the same as 
though the user had typed control-E at exactly the right instant. 



Control-U can be typed at any point, even in the middle of an atom; It 
simply sets an internal flag checked by lispxread . 

Control-U also works for calls to readline . i.e., for line commands. 
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valueof is an nlambda function for obtaining the value of 

a particular event, e.g. (VALUEOF -1), 
(VALUEOF ♦•FOO -2). 

The value of an event consisting of several 
operations is a list of the values for each of the 
individual operations. 



Notet the value field of a history entry is initialized to bell (control'-G) . 
Thus a value of bell indicates that the corresponding operation did not 
complete, i.e. toas aborted or caused an error (or else returned bell). 



prompt#flg is a flag which when set to T causes the current 

event number to be printed before each : and * 
prompt characters. See description of promptchar , 
page 22.51. 

prompt#flg is initially NIL. 



archivefn allows the user to specify events to be 

automatically archived. 



archivefn is set to T, and an event is about to drop off the end of the 
history list and be forgotten, archivefn is called giving it as its first 
argument the input portion of the event, and as its second argument, the entire 



Although the input for valueof is entered on the history list before 
valuoof is called, valueofC-1] still refers to the value of the expression 
immediately before the valueof input, because valueof effectively backs the 
history list up one entry when it retrieves the specified event. 
Similarly, (VALUEOF FOO) will find the first event before this one that 
contains a FOO. 
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event. If archivefn returns T, the event is archived. For example, some 
users like to keep a record of all calls to load. Defining archivefn as: 
(LAMBDA (X Y) (EQ (CAR X) (QUOTE LOAD))) will accomplish this. Note that 
archivefn must be both set and defined. archivefn is initially NIL and 
undef ined. 

« « K 

lispxmacros provides a macro facility for lispx . 

lispxmacros allows the user to define his own lispx commands. It is a list of 
elements of the form (command def). Whenever command appears as the first 
expression on a line in a lispx input, the variable lispxline is bound to the 
rest of the line, the event is recorded on the history list, and def is 
evaluated. Similarly, whenever command appears as car of a form in a lispx 
input, the variable lispxline is bound to cdr of the form, the event recorded, 
and def is evaluated. (See page 22.60 for an example of a lispxmacro ) . 
RETRIEVE, BEFORE, and AFTER are implemented as lispxmacros . In addition, LISP, 
SNDMSG, TECO, and EXEC are lispxmacros which perform the corresponding calls to 
subsys (section 21), and CONTIN is a lispxmacro which performs (SUBSYS T). 
Finally, SY and DIR are lispxmacros which perform the EXEC, SYSTAT, and 
DIRECTORY commands respectively. DIR can be given arguments, e.g., 
DIR *.SAV;«. 



In case archivefn needs to examine the value of the event, its side 
effects, etc. See page 22.44 for discussion of the format of history 
lists . 
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lispxuserfn provides a way for a user function to process 

selected inputs. 

When lispxuserfn is set to T, it is applied^^ to all inputs not recognized as 
one of the commands described above. If lispxuserfn decides to handle this 
input, it simply processes it (the event was already stored on the history list 
before lispxuserfn was called), sets lispxvalue to the value for the event, and 
returns T. lispx will then know not to call eval or apply , and will simply 
store lispxvalue into the value slot for the event, and print it. If 
lispxuserfn returns NIL, lispx proceeds by calling eval or apply in the usual 
way. Thus by appropriately defining (and setting) lispxuserfn , the user can 
with a minimum of effort incorporate the features of the programmer's assistant 
into his own executive (actually it is the other way around). 



Like archivefn, lispxuserfn must be both set and defined. 
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The following output illustrates such a coupling. 



**SETQ(ALTFORM (MAPCONC NASDIC (F/L (GETP X 'ALTFORMS] [1] 

=NASDICT 

(AL26 BE7 C056 C057 C060 C13 H3 MN54 NA22 SC46 S34 TI44) 
««(GIVEMELINESCONTAININGCOBALT) [2] 
SAMPLE PHASE CONSTIT. CONTENT UNIT CITATION TAG 

S10002 OVERALL C056 40.0 DPM/K6 D70-237 0 

C13 8.8 DEL 070-228 0 

H3 314.0 0PM/K6 

MN54 28 



««GETP(COBALT ALTFORMS) 

(C056 C057 C060 013 H3 NN54 NA22 SC46 S34 T144) 

««UNDO MAPCONC 

SETO UNDONE. 

««REDOGETP 

(C056 C057 C060) 

«*RED0 COBALT 



SAMPLE 
S10002 
S10003 



PHASE 

OVERALL 

OVERALL 



CONSTIT. 

C057 

CO 



C056 
C057 
CO60 

**USE MANGANESE FOR COBALT 



CONTENT 

40.0 

15.0 

14.1 

43.0 

43.0 

1.0 



UNIT 
DPM/KG 



DPM/K6 



CITATION 

D70-237 

D70-203 

D70-216 

D70-237 

D70-241 



[3] 

[4] 

[5] 

[6] 
TAG 
0 
0 

0 
0 



The user is running under his owi executive program which accepts requests in 
the form of sentences* which it first parses and then executes. The user first 
'innocently' computes a list of all ALTERKIAT I VE - FORMS for the elements in his 
system [1]. He then inputs a request in sentence format [2] expecting to see 
under the column CONSTIT. only cobalt. CO, or its alternate forms, €056, €057, 
or CO60. Seeing €13, H3, and NN54, he aborts the output, and checks the 
property ALTFORMS for COBALT [3]. The appearance of €13, H3, NN54, he aborts 
the output, and checks the property ALTFORMS for COBALT [3]. The appearance of 
€13, H3, NN54 et al, remind him that the mapconc is destructive, and that in 
the process of making a list of the ALTFORMS, he has inadvertently strung them 
all together. Recovering from this situation would require him to individually 



The output Is from the Lunar Sciences Natural Language Information System 
being developed for the NASA Manned Spacecraft Center by William A. Woods 
of Bolt Beranek and Newman Inc., Cambridge, Mass. 
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examine and correct the ALTFORMs for each element in his dictionary, a tedious 
process. Instead, he can simply UNDO MAPCONC, [4] check to make sure the 
ALTFORM has been corrected [5], then redo his original request [6] and 
continue. The UNDO is possible because the first input was executed by lispx ; 
the (GIVE ME LINES CONTAINING COBALT) is possible because the user defined 
lispxuserfn appropriately; and the REDO and USE are possible because the 
(GIVE ME LINES CONTAINING COBALT) was stored on the history list before It was 
transmitted to lispxuserfn and the user's parsing program. 

lispxuserfn is a function of two arguments, x and line , where x Is the first 
expression typed, and line the rest of the line, as read by readline (see page 
22.47). For example, if the user types FOO(A B C), x=FOO, and llne=((A 6 C)); 
if the user types (FOO A B C), xa(FOO A B C), and line=NIL; and if the user 
types FOO ABC, x^FOO and line=(A B C). 

Thus in the above example, lispxuserfn would be defined as: 

[LAMBDA (X LINE) 
(COND 

((AND (NULL LINE) 
(LISTP X)) 
(SETO LISPXVALUE (PARSE X)) 
T] 

Note that since lispxuserfn is called for each input (except for p. a. 
commands), it can also be used to monitor some condition or gather statistics. 

* « « 

In addition to saving inputs and values, lispx saves most system messages on 
the history list, e.g. FILE CREATED — , (fn REDEFINED), (var RESET), output of 
TIME, BREAKDOWN, STORAGE, DWIM messages, etc. When printhistory prints the 
event, this output is replicated. This facility is implemented via the 
functions lispxprint , lispxprinl . lispxprinZ . llspxspaces , lispxterpri , and 
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lispxtab . In addition to performing the corresponding output operation » these 
functions store an appropriate expression on the history event under the 
property LISPXPRINT.^^ This expression is used by printhistory to reproduce the 
output. 

« Ik « 

In addition to the above features* lispx checks to see if car or cdr of NIL or 
car of T have been clobbered, and if so, restores them and prints a message. 
Lispx also performs spelling corrections using lispxcoms , a list of its 
commands, as a spelling list whenever it is given an unbound atom or undefined 
function, i.e. before attempting to evaluate the input. 

22.6 Undoing 

The UNDO capability of the programmer's assistant is implemented by requiring 
that each operation that is to be undoable be responsible itself for saving on 
the history list enough information to enable reversal of its side effects. In 
other words, the assistant does not *know' when it is about to perform a 
destructive operation, i.e. it is not constantly checking or anticipating. 
Instead, it simply executes operations, and any undoable changes that occur are 



In fact, all six of these functions have the same definition. When called, 
this function looks back on the stack to see what name it was called by, 
and determines what to do. Thus, if the user wanted to make any other 
output function, e.g. printd ef, record its MOVD(LISPXPRINT LISPXPRINTOEF) , 
and then use lispxprlntdef for printdef . (This will work only for 
functions of three or fewer arguments.) 

unless lispxprintflg is NIL. 

lisp x is also responsible for rebinding helpclock . used by breakcheck . 
Section 16, for computing the amount of time spent in a computation, in 
order to determine whether to go into a break if and when an error occurs. 
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automatically saved on the history list by the responsible function. The 
operation of UNDOing, which involves recovering the saved information and 
performing the corresponding inverses, works the same way, so that the user can 
UNDO an UNDO, and UNDO that etc. 

At each point, until the user specifically requests an operation to be undone, 
the assistant does not know, or care, whether information has been saved to 
enable the undoing. Only when the user attempts to undo an operation does the 
assistant check to see whether any information has been saved. If none has 
been saved, and the user has specifically named the event he wants undone, the 
assistant types NOTHING SAVED. (When the user simply types UNDO, the assistant 
searches for the last undoable event, ingnoring events already undone as well 
as UNDO operations themselves.) 

This implementation minimizes the overhead for undoing. Only those operations 
which actually make changes are affected, and the overhead is small: two or 
three cells of storage for saving the information, and an extra function call. 
However, even this small price may be too expensive if the operation is 
sufficiently primitive and repetitive, i.e. if the extra overhead may seriously 
degrade the overall performance of the program.^' Hence not every destructive 
operation in a program should necessarily be undoable; the programmer must be 
allowed to decide each case individually. 



When the number of changes that have been saved exceeds the value of 
#undosavos (initially set to 50), the user is asked if he wants to continue 
saving the undo information for this event. The purpose of this feature is 
to avoid tying up large quantities of storage for operations that will 
never need to be undone. The interaction is handled by the same routines 
used by DWIM, so that the input buffers are first saved and cleared, the 
message typed, then the system waits dwimwait secon<^s, and if there is no 
response, assumes the default answer, which in this case is NO. Finally 
the input buffers are restored. See page 22.56 for details. 



The rest of the discussion applies only to lispx ; the editor handles 
undoing itself in a slightly different fashion, as described on page 
22.61. 
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Therefore for each primitive destructive operation, we have implemented two 

separate functions, one which always saves information, i.e. is always 
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undoable, and one which does not, e.g. / rplaca and rplaca , /put and put . In 
the various system packages, the appropriate function is used. For example, 
break uses /putd and /remprop so as to be undoable, and DWIN uses /rplaca and 
/rplacd , when it makes a correction. Similarly the user can simply use the 
corresponding / function if he wants to make a destructive operation in his own 
program undoable. When the / function is called, it will save the undo 
information in the current event on the history list. 

However, all operations that are typed in to lispx are made undoable, simply by 
substituting the corresponding / function for any destructive function 
throughout the input .^^ For example, on page 22.8, when the user typed 
(MAPCONC NASOIC (F/L ...)) it was (/MAPCONC NASOIC (F/L ...)) that was 
evaluated. Since the system cannot know whether efficiency and overhead are 
serious considerations for the execution of an expression in a user program, 
the user must decide, e.g. call /mapconc if he wants the operation undoable. 



The 'slash' functions currently implemented are /addprop , /attach , 
/d rcmo ve , /dreverse , /dsubs t , /Iconc , /mapcon , /mapconc , /movd , /nconc , 
/ nco ncl , /put , /putd , /putdq" /puthash , /remprop , /rplaca , /rplacd , /set , 
/seta , /setd , and /tconc . Note that /setq and /setqq are not Included. If 
the user wants a set operation undoable in his program, he must see /set , 
or /rplaca . 



The effects of the following functions are always undoable (regardless of 
whether or not they are typed in): dcf ine , dcf ineq , defc (used to give a 
function a compiled code definition), def list , load , savedef , unsavedef , 
bronk, unb reak , rcbreak , trace , breakin , unbreakin . changename , editfns , 
oditf , editv, editp , edite , editl , esubst , advise , unadvise, readvise , plus 
any changes caused by DWIN. 
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Since there is no /setq , set q's appearing in type-in are handled specially 
by substituting a call to s aveset . page 22.43. 
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The substitution is performed by the function lispx/ . described on page 
22.58. 
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However, expressions that are typed-in rarely involve iterations or lengthy 
computations directly. Therefore, if all primitive destructive functions that 
are inunodiately contained in a type-in are made undoable, there will rarely be 
a significant loss of efficiency. Thus lispx scans all user input before 
evaluating it, and substitutes the corresponding undoable function for all 
primitive destructive functions. Obviously with a more sophisticated analysis 
of both user input and user programs, the decision concerning which operations 
to make undoable could be better advised. However, we have found the 
configuration described here to be a very satisfactory one. The user pays a 
very small price for being able to undo what he types in, and if he wishes to 
protect himself from malfunctioning in his own programs, he can have his 
program specifically call undoable functions, or go into testmode as described 
next. 

Testmode 

Because of efficiency considerations, the user may not want certain functions 
undoable after his program becomes operational. However, while debugging he 
may find it desirable to protect himself against a program running wild, by 
making primitive destructive operations undoable. The function testmode 
provides this capability by temporarily making everything undoable. 

testmodeCflg] testmode[Tl redefines all primitive destructive 

functions with their corresponding undoable 
versions and sets testmodeflg to T. testmode[ ] 
restores the orialnal definitions, and sets 
testmodeflg to NIL. 



i.e. the 'slash' functions; see footnote on page 22.40. 

testmode will have no effect on compiled mapconc 's, since they compile open 
with frplacd 's. 
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Note that setq 's are not undoable, even in testroode . To make the corresponding 
operation undoable in testmode . set or rplaca should be used. 



Undoing Out of Order 

/rplaca and /rplacd operate by saving the pointer that is to be changed and its 
original contents (i.e. /rplaca saves car and /rplacd saves cdr ) . Undoing 
/rplaca and /rplacd simply restores the pointer. Thus, if the user types 
(RPLACA FOO 1), followed by (RPLACA FOO 2), then undoes both events by undoing 
the most recent event first, then undoing the older event, FOO will be restored 
to its state before either rplaca operated. However if the user undoes the 
first event, then the second event, (CAR FOO) will be 1, since this is what was 
in car of FOO before (RPLACA FOO Z) was executed. Similarly, if the user 
performs (NCONCl FOO 1) then (NCONCl FOO 2), undoing Just (NCONCl FOO 1) will 
remove both 1 and 2 from FOO. The problem in both cases is that the two 
operations are not 'independent.' In general, operations are always independent 
if they affect different lists or different sublists of the same list.^^ 
Undoing in reverse order of execution, or undoing independent operations, is 
always guaranteed to do the 'right' thing. However, undoing dependent 
operations out of order may not always have the predicted effect. 



Property list operations, (i.e. put , addprop and remprop ) are handled 
specially so that they are always independent, even when they affect the 
same property list. For example, if the user types PUT(FOO FIEl FUMl) then 
PUT(FOO FIE2 FUM2), then undoes the first event, the FIE2 property will 
remain, even though CDR(FOO) may have been NIL at the time the first event 
was executed. 
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Saveset 



Sotq ' s are made undoable on type in by substituting a call to saveset 
(described in detail on page 22.55), whenever setq is the name of the function 
to be applied, or car of the form to be evaluated. In addition to saving 
enough information on the history list to enable undoing, saveset operates in a 
manner analogous to savedef when it resets a top level value, i.e. when it 
changes a top level binding from a value other than NOBINO to a new value that 
is "ot equal to the old one. In this case, saveset saves the old value of the 
variable being set on the variable's property list under the property VALUE, 
and prints the message (variable RESET). The old value can be restored via the 
function unset , which also saves the current value (but does not print a 
message). Thus unset can be used to flip back and forth between two values. 

rpaq and rpaqq are implemented via calls to saveset . Thus old values will be 

saved and messages printed for any variables that are reset as the result of 

no 

loading a file. Calls to set and setqq appearing in type in are also 
converted to appropriate calls to saveset . 

For top level variables, saveset also adds the variable to the appropriate 
spelling list, thereby noticing variables sat in files via rpaqq or rpaqq . as 
well as those set via type in. 



Of course, UNDO can be used as long as the event containing this call to 
saveset is still active. Note however that the old value will remain on 
the property list, and therefore be recoverable via unset , even after the 
original event has been forgotten. 

To complete the analogy with define , saveset will not save old values on 
property lists if dfnf lg =T, e.g. when load is called with second argument 
T, (however, the call to saveset will still be undoable,) and when 
dfnf l g=ALLPROP, the value is stored directly on the property list under 
property VALUE (the latter applies only to calls from rpaqq and rpaq ) . 
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22.7 Format and Use of the History List 

There are currently two history lists, llspxhistory and edithistory . Both 
history lists have the same format, and in fact, each use the same function, 
historysave , for recording events, and the same set of functions for 
implementing commands that refer to the history list, e.g. historyf ind , 
printhistory , undosave, etc.^^ 

Each history list is a list of the form (1 event# size mod), where 1 is the 
list of events with the most recent event first, event# is the event number for 
the most recent event on 1, size is the size of the time-slice, i.e. the 
maximum length of 1, and mod is the highest possible event number (see footnote 
on page 22.8). lispxhistory and edithistory are both initialized to 
(NIL 0 30 100). Setting lispxhistory or edithistory to NIL is permitted, and 
simply disables all history features, i.e. lispxhistory and edithistory act 
like flags as well as repositories of events. 

Each individual event on 1 is a list of the form (input id value . props), 
where input is the input sequence for the event, as described on page 22.17-19, 
id the prompt character, e.g. :, «,*''^ and value is the value of the event, 
and is initialized to bell.^^ 
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A third history list, archivelst , is used when events are archived, as 
described on page 22.27. It too uses the same format. 

id is one of the arguments to lispx and to historysave . A user can call 
lispx giving it any prompt character he wishes (except for *, since in 
certain cases, lispx must use the value of id to tell whether or not it was 
called from the editor.) For example, on page 22.36, the user's prompt 
character was **. 

On edithistory , this field is used to save the side effects of each 
command . 
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props is a property list, i.e. of the form (property value property value --). 
props can be usee! to associate arbitrary information with a particular event. 
Currently, the properties SIDE. GROUP, HISTORY. PRINT. USE-ARGS. ...ARCS, 
ERROR, and LISPXPRINT are being used. The value of property SIDE is a list of 
the side effects of the event. (See discussion of undosave , page 22.56. and 
undolispx . page 22.58). The HISTORY and GROUP properties are used for 
commands that reexecute previous events, i.e. REDO, RETRY, USE, and FIX. 

The value of the HISTORY property is the history command Itself, i.e. what the 
user actually typed, e.g. REDO FROH F, and is used by the ?? command for 
printing the event. The value of the property PRINT is also for use by the ?? 
command, when special formatting is required, for example, in printing events 
corresponding to the break commands OK, GO, EVAL, and ?s« USE-ARGS and . . .ARGS 
are used to save the arguments and expression for the corresponding history 
command. ERROR is used by the $ command. LISPXPRINT is used to record calls 
lispxprint , lispxprinl , et al. See page 22.37. 

When lispx is given an input, it calls historysave to record the input in a new 
event. Normally, historysave returns as its value cddr of the new event, i.e. 
car of its value is the value field of the event, lispx binds lispxhist to the 
value of historysave , so that when the operation has completed, lispx knows 
where to store the value, namely in car of lispxhist .^ lispxhist also provides 
access to the property list for the current event. For example, the / 
functions are all implemented to call undosave , which simply adds the 
corresponding information to lispxhist under the property SIDE, or if there is 
no property SIDE, creates one, and then adds the information. 



The commands ??, FORGET, TYPE-AHEAD, SBUFS, and ARCHIVE are executed 
immediately, and are not recorded on the history list. 



Note that by the time it completes, the operation may no longer correspond 
to the most recent event on the history list. For example, all inputs 
typed to a lower break will appear later on the history list. 
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After binding lispxhist , lispx executes the input, stores its value in car of 
lispxhist , prints the value, and returns. 

When the input is a REDO, RETRY, USE, or FIX command, the procedure is 

similar, except that the event is also given a GROUP property, initially NIL, 
and a HISTORY property, and lispx simply unreads the input and returns. When 
the input is 'reread', it is hlstorysave , not lispx , that notices this fact, 
and finds the event from which the input originally came.^^ historysave then 
adds a new (value . props) entry to the GROUP property for this event, and 
returns this entry as the 'new event.' lispx then proceeds exactly as when its 
input was typed directly, i.e. it binds lispxhist to the value of historysave , 
executes the input, stores the value in car of lispxhist , prints the value, and 
returns. In fact, lispx never notices whether it is working on freshly typed 
input, or input that was reread. Similarly, undosave will store undo 
information on lispxhist under the property SIDE the same as always, and does 
not know or care that lispxhist is not the entire event, but one of the 
elements of the GROUP property. Thus when the event is finished, its entry 
will look like: 

(input id value HISTORY command GROUP ((valuel SIDE sidel) 

(value2 SIDE side2) ^„ 
...)) 

This implementation removes the burden from the function calling historysave of 
distinguishing between new input and reexecution of input whose history entry 



If historysave cannot find the event, for example if .a user program unreads 
the input directly, and not via a history command, historysave proceeds as 
though the input were typed. 



In this case, the value field is not being used; valueof instead collects 
each of the values from the GROUP property, i.e. returns 
mapcarC get[ event ;GROUP];CAR]„ Similarly, undo operates by collecting the 
SIDE properties from each of the elements of the GROUP property, and then 
undoing them in reverse order. 
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has already been set up. 



22.8 lispx and readline 

lispx is called with the first expression typed on a line as its first 
argument, lispxx . 

If this is not a list, lispx almys does a readline , and treats lispxx plus the 
line as the input for the event, and stores it accordingly on the history 
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list. Then it decides what to do with the input, i.e. if it is not recognized 
as a command, a lispxmacro , or is processed by lispxuserfn , call eval or 
apply . readline normally is terminated either by (i) a carriage return that 
is not proceeded by a space, or (2) a list that is terminated by a ], or (3) an 
unmatched ) or ], which is not included in the line. However, when called from 
lispx , readline operates differently in two respects: 

(1) If the line consists of a single ) or ], readline returns (NIL) 
instead of NIL, i.e. the ) or ] included in the line. This permits 
the user to type FOO) or FOO], meaning call the function' FOO with no 
arguments, as opposed to FOO^ (FOOcarriage-return) , meaning evaluate 
the variable FOO. 

(2) If the first expression on the line is a list that is not preceded by 



Although we have not yet done so, this implementation, i.e. keeping the 
various 'sub-events' separate with respect to values and properties, also 
permits constructing commands for operating on Just one of the sub-events. 



69 



60 



llspxx is a list car of which is LAMBDA or NLAMBOA, lispx calls 
lispxread to obtain the arguments. 

If the input consists of one expression, eval is called; if two, apply ; if 
more than two, the entire line is treated as a single form and eval is 
called. 
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any spaces, the list terrainates the line regardless of whether or not 
it is terminated by ]. This permits the user to type EDITF(FOO) as a 
single input. 

Note that if any spaces are inserted between the atom and the left parentheses 
or bracket, readline will assume that the list does not terminate the line. 
This is to enable the user to type a line command such as USE (FOO) FOR FOO. In 
this case, a carriage return will be typed after (FOO) followed by as 
described in Section 14. Therefore, if the user accidentially puts an extra 
space between a function and its arguments, he will have to complete the input 
with another carriage return, e.g. 

«-EDITFJFOO) 

EDIT 
* 

22.9 Functions 

lispxC lispxx; lispxid ; lispxxmacros ; lispxxuserfn 

lispx is like eval / apply . It carries out a single 
computation, and returns its value. The first 
argument, lispxx is the result of a single call to 
lispxread . lispx will call readline . if necessary 
as described on page 22.47. lispx prints the 
value of the computation, as well as saving the 



lispxid corresponds to id on page 22.44. Lispx also has a fifth argument, 
lispxf Ig , which is used by the E command in the editor. 
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Input and value on lispxhlstory . 



lispxx is a history command, lispx executes the 
command, and returns bell as its value. 
If the value of the fourth argument, lispxxrnacros , 
is not NIL, it is used as the lispx macros, 
otherwise the top level value of lispxmacros is 
used. If the value of the fifth argument, 
lispxxuserfn . is not NIL, it is used as 
lispxuserfn . In this case, it is not necessary to 
both set and define lispxuserfn as described on 
page 22.35. 

The overhead for a call to lispx is approximately 17 milliseconds, of which 12 
milliseconds are spent in maintaining the spelling lists. In other words, in 
INTERLISP, the user pays 17 more milliseconds for each eval or apply input over 
a conventional LISP executive, in order to enable the features described in 
this chapter. 

userexec[ lispxid ; lispxxrnacros *, lispxxuserfn ] 

repeatedly calls lispx under errorset protection 
specifying lispxxrnacros and lispxxuserfn , and 
using lispxid (or if lispxid =NIL) as a prompt 
character. Userexec is exited via the lispxmacro 
OK, or else with a retfrom . 



Note that the history is not one of the arguments to lispx , i.e. the editor 
must bind (reset) lispxhlstory to edithistory before calling lispx to carry 
out a history command. 

Lispx will continue to operate as an eval / apply function if lispxhistory is 
NIL. Only those functions and commands that involve the history list will 
be affected. 
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lispxread[f lie] is a generalized read . If readbufsNIL, lispxread 

performs read[file], which it returns as its 
value. (If the user types control-U during the 
call to read , lispxread calls the editor and 
returns the edited value.) 

If readbuf is not NIL, lispxread 'reads* the next 

expression on readbuf , i.e. essentially returns 

(PROGl (CAR READBUF) ^« 
(SETQ READBUF (CDR READBUF))).**** 

readline , described in Section 14, also uses this generalized notion of 
reading. When readbuf is not NIL, readline 'reads' expressions from readbuf 
until it either reaches the end of readbuf , or until it reads a (VAG 0). In 
both cases, it returns a list of the expressions it has 'read*. (The (VAG 0) 
Is not included In the list.) 

When readbuf is not NIL, both lispxread and readline actually obtain their 
input by performing (APPLY* LISPXREAOFN FILE), where lispxreadfn is initially 
set to READ. Thus, if the user wants lispx , the editor, break, et al to do 
their reading via a different input function, e.g. uread, he simply sets 
lispxreadfn to the name of that function (or an appropriate LAMBDA expression). 

lispxreadpCf Ig] is a generalized readp . If flfl=T, lispxreadp 

returns T if there is any input waiting to be 
'read', a la lispxread . If f lg =NIL, lispxreadp 
returns T only if there is any input waiting to be 
'read' on this line. In both cases, leading spaces 



Except that pseudo-carriagct returns, as represented by (VAG 0), are 
ignored. I.e. skipped. Lispxread also sets rereadf Ig to NIL when it reads 
via read , and sets rereadf Ig to the value of readbuf when rereading. 
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are ignored, i.e. skipped over with readc , so that 
if only spaces have been typed, lispxreadp will 
return NIL. 

lispxunread[lst] unreads 1st , a list of expressions to be read. If 

readbuf is not NIL, lispxunread attaches 1st at 
the front of readbuf , separating it from the rest 
readbuf with a (VAG 0). The definition of 

lispxunread is: 

(LISPXUNREAD 
[LAMBDA (LST) 

(SETQ READBUF (COND 
((NULL READBUF) 
LST) 

(T (APPEND LST (CONS (VAG 0) 

READBUF]) 

promptchar[id;f Igihist] prints the prompt character id. 

promptchar will not print anything when the next 
input will be 'reread', i.e. readbuf is not NIL. 
promptchar will also not print when readp[ ]sT, 
unless fig is T. 

Thus the editor calls promptchar with flgsNIL so that extra *'s are not printed 
when the user types several commands on one line. However, evalqt calls 
promptchar with flfl'T since it always wants the printed (except when 
'rereading' ) . 

Finally, if prompt#flg is T and hist is not NIL, 
promptchar prints the current event number (of 
hist) before printing id. 
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lispxeval[ lispxform;lispxid] evaluates lispxform (using eval) the same as 

though it were typed in to llspx » i.e. the event 
is recorded, and the evaluation is made undoable 
by substituting the slash functions for the 
corresponding destructive functions, as described 
on page 22.40. lispxeval returns the value of the 
form, but does not print it. 

historysave[history; id; input 1 ; input2 ; input3 ; props] 

records one event on history . If inputl is not 
NIL, the input is' of the form 
(input! input2 . input3). If inputl is NIL, and 
input2 is not NIL, the input is of the form 
(input2 . input3). Otherwise, the input is Just 
inputs . 

historysave creates a new event with the 
corresponding input, id, value field initialized 
to bell, and props . If the history has reached 
its full size, the last event is removed and 
cannibalized. 

The value of historysave is cddr of the event. 
However, if rereadf Ig is not NIL, and is a tail of 
the input of the most recent event on the history 
list, and this event contains a GROUP property, 
historysave does not create a new event, but 
simply adds a (bell . props) entry to the GROUP 
property and returns that entry. See discussion 
on page 22.46. 
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lispxfindC history; line; type ;bacliup] 

line is an event specification » type specifies the 
format of the value to be returned by lispxf ind , 
and can be either ENTRY, ENTRIES, COPY, COPIES, 
INPUT, or REDO, lispxf ind parses line , and uses 
historyfind to find the corresponding events. 
lispxf ind then assembles and returns the 
appropriate structure. 

lispxf ind incorporates the following special features: 

if backup sT, lispxf ind interprets line in the context of the history list 
before the current event was added. This feature is used, for example, by 
valueof , so that (VALUEOF -I) will not refer to the valueof event itself; 

{Z) if line =NIL and the last event is an UNDO, the next to the last event is 
taken. This permits the user to type UNDO followed by REDO or USE; 

lispxf ind recognizes 0@, and substitutes archivelst for history (see page 
22.14); and 

lispxf ind recognizes 9, and retrieves the corresponding event(s} from the 
property list of the atom following 9 (see page 22.14). 

historyf ind[ 1st ;index;mod;x;y] 

searches 1st and returns the tails of 1st 
beginning with the event corresponding to x. 1st , 
index , and mod are as described on page 22.44. 
X is an event address, as described on page 
22.11-14, e.g. (43), (-1), (FOO FIE), 
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(LOAD FOO), etc. ^ If historyfind cannot find x. 
it generates an error. 

entry#Chist;x] hist is a history list, i.e. of the form described 

on page 22.44. x is one of the events on hist , 
i.e. (NEMB X (CAR HIST)) is true. The value of 
entry# is the event number for 3$. 

valueof[x] is an nlambda, nospread function for obtaining the 

value of the event specified by x, o.g^ 
(VALUEOF -1), (VALUEOF LOAD 1), etc. valueof 
returns a list of the corresponding values if x 
specifies a multiple event. 

( 

changesliceCn ;history] changes time-slice for history to n. If history 

is NIL, changes both edithistory and lispxhistory . 

Note: the effect of increasing a time-slice is gradual: the history list is 
simply allowed to grow to the corresponding length before any events are 
forgotten. Decreasing a time-slice will immediately remove a sufficient number 
of the older events to bring the history list down to the proper size. 
However, changeslice is undoable, so that these events are (temporarily) 
recoverable. Thus if the user wants to recover the storage associated with 
these events without waiting n more events for the changeslice event to be 
forgotten, he must perform a FORGET command. 
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If Y is given, the event address is the list difference between x and 
e.g. x=(FOO FIE AND \ -1), ^^(AND \ -1) is equivalent to 

x=(FOO FIE), ;^=NIL. 



6S 

changeslice has a third argument used by the system for undoing a 

changeslice 
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saveset[ name ; value ; topflg ; fig ] 

an undoable set , (see page 22.43). savesct scans 
the pushdown list looking fpr the last binding of 
name, sets name to value , and returns value . 

If the , binding changed was a top level binding, 
name is added to spellings3 (see Section 17). 
Furthermore, if the old value was not NOBINOp and 
was also not equal to the new value, saveset calls 
the file package to update the necessary file 
records. Then, if dfnflg is not equal to T, 
saveset prints (name RESET), and saves the old 
value on the property list of name , under the 
property VALUE. If flgsNOPRINT, saveset saves the 
old value, but does not print the message. This 
option is used by unset . 

topflg sT, saveset operates as above except that 
it does not scan the pushdown list but goes right 
to name's value cell, e.g. rpaqq[x;y] is simply 
saveset[x;y;T]. When topflg is T, and dfnflg is 
ALLPROP and the old value was not NOBINO, saveset 
simply stores value on the property list of name 
under the property VALUE, and returns value. This 
option is used for loading files without 
disturbing the current value of variables (see 
Section 14) . 

If flg sNOSAVE, saveset does not save the old value 
on the property list, nor does it add name to 
spellings3 . However, the call to saveset is still 
undoable. This option is used by /set . 
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unset[naine] if name does not contain a property VALUE, unset 

generates an error. Otherwise unset calls saveset 
with name , the property value, topf Ig sT, and 
flfl=NOPRINT. 

lispxhist is not NIL (see discussion on page 
22.45), and get[ lispxhist ;SIOE] is not equal to 
NOSAVE, undosave adds undoform to the value of the 
property SIDE on lispxhist , creating a SIDE 
property if one does not already exist. The form 
undoforro is (fn . args),^^ i.e. undoform is 
undone by performing 

apply[car[undoform];cdr[undoform]]. For example, 
if the definition of FOO is def, /putd[FOO;newdef ] 
will cause a call undosave with 
undoform s(/PUTO FOO def). 

car of the SIDE property is the number of 
'undosaves', i.e. length of cdr of the SIDE 
property, which is the list of undoforms . Each 
call to undosave increments this count, and adds 
undoform to the front of the list, i.e. just after 
the count. When the count reaches the value of 
#undosaves (initially 50),^^ undosave prints a 



undosaveC undoform] 



Undosave has a second optional argument, histentry , which can be used to 
specify lispxhist directly, saving the time to look it up. If both 
histentry and lispxhist are NIL, undosave is a NOP. 



Except for /rplnode , as described below. 
#undosavos =NIL is equivalent to #undosavess infinity. 
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message asking the user if he wants to continue 
saving. If the user answers NO or defaults, 
undosave makes NOSAVE be the value of the property 
SIDE, which disables any further saving for this 
event. If the user answers YES, undosave changes 
the count to -1, which is then never incremented, 
and continues saving. 

/rplnode[x;a;d] Undoably performs rplaca[x;a] and rplacd[x;d]. 

Value is x. The principle advantage of /rplnode 
is that when x ^ list, /rplnode saves its undo 
information as consCx;cons[car[x];cdr[x]]], i.e. 
(x originalcar . originalcdr), and therefore 
requires only 3 cells of storage, instead of the 8 
that would be required for a /rplaca and a /rplacd 
that saved their information as described 
earlier. 

/rplnode has a BLKLIBRARYOEF.. 

n€jw/fn[fn] After the user has defined /fn, new/fn performs 

the necessary housekeeping operations to make fn 
be undoable. 



69 



70 



load initializes the count on SIDE to -1, so that regardless of the value 
>^undosaves , no message will be printed, and the load will be undoable. 

Actually, /rplaca and /rplacd also use this format for saving their undo 
information when their first arguments are lists. However, if both a 
/rplaca and /rplacd are to be performed, it is still more efficient to use 
/rplnode (3 cells versus 6 cells). 
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For example, the user could define /radix as 

(LAMBDA (X) (UNDOSAVE (LIST (QUOTE /RADIX) (RADIX X))) and then perform 
new/fn[ radix], and radix would then be undoable when typed in or in testmode. 



lispx/Cx;fn;vars] performs the substitution of / functions for 

destructive functions. If fn is not NIL, it is 
the name of a function, and x is its argument 
list. If fn is NIL, x a form. In both cases, 
li&px/ returns x with the appropriate 
substitutions. Vars is a list of bound variables 
(optional). 

lispx/ incorporates information about the syntax 
and semantics of INTERLISP expressions. For 
example, it does not bother to make undoable 
operations involving variables bound in x* 
also knows that substitution should not be 
performed inside of expressions car of which is 
QUOTE, DEFINEQ. BREAK, etc.^^ Similarly, 
substitution should be performed in the arguments 
for functions like mapc , rptq , etc., since these 
contain expressions that will be evaluated or 
applied. For example, if the user types 
mapc[(F001 F002 F003);PUTD] the putd must be 
replaced by /putd . 

undolispx[line] line is an event specification, undolispx is the 

function that executes UNDO commands by calling 
undolispxl on the appropriate entry(s). 



Any member of the list nosubstfns. 
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undolispxl[event;f Ig] undoes jpne event. The value of undolispxl is NIL 

if there is nothing to be undone. If the event is 
already undone, undolispxl prints ALREADY UNDONE 
and returns T. Otherwise, undolispxl undoes the 
event, prints a message, e.g. SETQ UNDONE, and 
returns T. 

Undoing an event consists of mapping down ( cdr of) the property value for SIDE, 
and for each element, applying car to cdr, and then marking the event undone by 
attaching (with / attach ) a NIL to the front of its SIO£ property. Note that 
the undoing of each element on the SIDE property will usually cause undosaves 
to be added to the current lispxhist . thereby enabling the effects of 
undolispxl to be undone. 

undonlsetqCform] is an nlambda function similar to nlsetq . 

undonlsetq evaluates form , and if no error occurs 
during the evaluation, returns list[evalC form]] 
and passes the undo information from form (if any) 
upwards. If an error does occur, the value of 
undonlsetq is NIL, and any changes made by / 
functions during the evaluation of form are 
undone. 



72 



73 



If f lg =T and the event is already undone, or is an undo command, undolisp xl 
takes no action and returns NIL. Undolispx uses this option to search for 
the last event to undo. Thus when lino =NIL, undolispx simply searches 
history until it finds an event for which undolispxl returns T, i.e. 
undolispx performs (SOME (CDAR LISPXHISTORY) (F/L (UNOOLISPXl XT))) 

Actually, undonlsetq does not rebind lispxhist , so that any undo 
information is stored directly on the history event, exactly as though 
there were no undonlsetq . Instead, undonlsetq simply marks the state of 
the undo information when it starts, so that if an error occurs, it can 
then know how much to undo. The purpose of this is so that if the user 
control-O's out of the undonlsetq, the event is still undoable. 
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undonlsetq compiles open. 



undonlsetq will operate even if lispxhistory or 
lispxhlst are NIL, or if #undosaves is or has been 
exceeded for this event. 

Note that undonlsetq provides a limited form of backtracking. 

pr in th is tory[ history; line ;skipfn;novalues] 

line is an event specification. printhistory 
prints the events on history specified by line , 
e.g. (-1 THRU -10). skipfn is an (optional) 
functional argument that is applied to each event 
before printing. If its value is true, the event 
is skipped, i.e. not printed. If novalues sT, or 
novalues applied to the corresponding event is 
true, the value is not printed/^ 

For example, the following lispxtTiacr*o will define ??' as a command for printing 
the history list while skipping all 'large events' and not printing any values. 



(??• (PRINTHISTORY LISPXHISTORY LISPXLINE 
(FUNCTION (LAMBDA (X) 

(IGREATERP (COUNT (CAR X)) 5))) 
T)) 
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For example, novalues is T when printing events on edithistory . 
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22.10 The Editor and the Assistant 



As mentioned earlier, all of the remarks concerning *the assistant' apply 
equally well to user interactions with evalqt , break or the editor. The 
differences between the editor's implementation of these features and that of 
lispx are mostly obvious or inconsequential. However » for completeness, this 
section discusses the editor's implementation of the programmer's assistant. 

The editor uses promptchar to print its prompt character, and lispxread , 
lispxreadp , and readline for obtaining inputs. When the editor is given an 
input, it calls historysave to record the input in a new event on its history 
list, edithistory . Edithistory follows the same conventions and format as 
lispxhistory . However, since edit commands have no value, the editor uses the 
value field for saving side effects, rather than storing them under the 
property SIDE. 

The editor processes 00, !E, !F, and !N commands itself, since lispx does not 
recognize these commands. The editor also processes UNDO itself, as described 
below. All other history commands^^ are simply given to lispx for execution, 
after first binding (resetting) lispxhistory to edithistory . The editor also 



Except that the atomic 
recorded. In addition, 
event. For example, 3 
position . 



commands OK, STOP, SAVE, P, 
number commands are grouped 
3 -1 is considered as one 



?, PP and E are not 
together in a single 
command for changing 



as indicated by their appearance on historycoms , a list of the history 
commands, editdc fault interrogates historycoms before attempting spelling 
correction. (All of the commands on historycoms are also on editcomsa and 
cditcomsl so that they can be corrected if misspelled in the editor.) Thus 
if the user defines a lispxmacro and wishes it to operate in the editor as 
well, he need simply add it to historycoms . For example, RETRIEVE is 
implemented as a lispxmacro and works equally well in lispx and the editor. 
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calls lispx when given an E command as described in Section 9. 



The major implementation difference between the editor and lispx occurs in 
undoing. Edithistory is a list of only the last n commands* where n is the 
value of the time-slice. However the editor provides for undoing all changes 
made in a single editing session, even if that session consisted of more than n 
edit commands. Therefore, the editor saves undo information independently of 
the edithistory on a list call undolst , (although it also stores each entry on 
undolst in the field of the corresponding event on edithistory . ) Thus, the 
commands UNDO, 'UNDO, and UNBLOCK, are not dependent on edithistory . I.e. 
UNDO specifies undoing the last command on undolst , even if that event no 
longer appears on edithistory . The only interaction between UNDO and the 
history list occurs when the user types UNDO followed by an event 
specification. In this case, the editor calls lispxf ind to find the event, and 
then undoes the corresponding entry on undolst . Thus the user can only undo a 
specified command within the scope of the edithistory . (Note that this is also 
the only way UNDO commands themselves can be undone, that is, by using the 
history feature, to specify the corresponding event, e.g. UNDO UNDO.). 

The implementation of the actual undoing is similar to the way it is done in 
lispx ; each command that makes a change in the structure being edited does so 
via a function that records the change on a variable. After the command has 
completed, this variable contains a list of all the pointers that have been 



In this case, the editor uses the fifth argument to lispx , lispxf Ig , to 
specify that any history commands are to be executed by a recursive call to 
lisp x, rather than by unreading. For example, if the user types E REDO in 
the editor, he wants the last event on lispxhistory processed as lispx 
input, and not to be unread and processed by the editor. 



and in fact will work if edithistory sNIL. or even in a system which does 
not contain lispx at all. 
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changed and their original contents. Undoing that command simply involves 
mapping down that list and restoring the pointers. 

22.11 Statisti cs 

The programmer's assistant keeps various statistics about system usage, e.g. 
number of lispx inputs, number of undo saves, number of calls to editor, numljer 
of edit commands, number of p. a. commands, cpu time, console time, et al. 
These can be viewed via the function lispxstats . 

lispxstats[3 prints statistics. 

The user can add his own statistics to the lispx statistics via the function 
addstats 

addstats[statlst] no spread, nlambda. Statist is a list of elements 

of the form (statistic-name . message), e.g. 
(EOITCALLS CALLS TO EDITOR) (UNDOSTATS CHANGES 
UNDONE), etc. statistic-name is set to the cell 
in an unboxed array, where the corresponding 
statistic will be stored. This statistic can then 
be incremented by lispxwatch . 

Iispxwatch[stat;n3 increments stat by n (or 1 if nsNIL). lispxwatch 

has a BLKLIBRARYDEF. 

The user can save his statistics for loading into a new system by performing 

MAKEFILF.(OUMPSTATS). After the file OUHPSTATS is loaded, the statistics printed 
lisp xstats will be the same as those that would be printed following the 
makefile. 
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ZZAZ Greeting and User Initialization 



Many of the features of INTERLI5P are parameterized to allow the user to adjust 
the system to his or her ovni tastes. Among the more commonly adjusted 
parameters are prompt#f Ig , dwimwait . changeslice , #rpars , lowercase , archivefn , 
#undosaves , f Itfmt , etc. In addition, the user can modify the action of system 
functions in ways not specifically provided for by using advise (Section 19). 

In order to encourage this procedure, and to make it as painless and automatic 
as possible, the p. a. includes a facility for a user-defined profile. When 
INTERLISP is first run, a specially formatted file on the LISP file directory 
is indexed into using the user's usernumber as a key. The expressions (if any) 
found there are then evaluated, and the p. a. prints a greeting, e.g., 
"HELLO, WARREN." or "GOOD AFTERNOON, DANNY.", etc. 

Greeting (i.e., the initialization) is undoable, and is stored as a separate 
event on the history list. The user can also specifically invoke the greeting 
operation via the function greet , for example, if he wishes to effect another 
user's initialization. 

greet[name;f Ig] performs greeting for user whose username is name , or 

if name sNIL, for login name (see username and 
usernumber . Section 21), i.e., when INTERLISP first 
starts up, it performs greet[]. Before greet performs 
the indicated initialization, it first undoes the 

7Q 

effects of the previous greeting. If f Ig sT, greet 
also resets the counters for the various statistics 
reported by lispxstats (page 22.63). 



The side effects of the greeting operation are stored on a global variable 
as well as the history list, thus enabling the previous greeting to be 
undone even if it is no longer on the history list. 
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greet also sets the variable usernaine to the name for which the greeting was 
performed. Sysin is advised to compare username with username[]» and to print 
a message alerting the user if they are not the same. For example, if user 
HARTLEY performs a sysin of a sysout made by user GOODWIN, the following 
message is printed: 

ATTENTION USER HARTLEY: 
THIS SYSOUT IS INITIALIZED FOR USER^GOOOWIN . 
TOREINITIALIZE,TYPEGREET() 

I mplementation 

greet operates off the file <LISP>USERNAMEFILE. To change an existing 
initialization, or create a new one, a new <LISP>USERNAMEFILE must be written. 
This is accomplished by loading the file <LISP>USERNANES, editing usernamelst , 
and then performing makeusernames[ ], which will create new versions of both 
USERNAMEFILE and USERNAMES. (Note that the person performing this operation 
must therefore either be connected to the LISP directory, or have write access 
to it . ) 

usernamelst is a list of elements of the form (username firstname T . forms), 
e.g., (TEITELMAN WARREN T (CHANGESLICE 100) (SETQ DWINWAIT 5)). cadr of the 
list is used in the greeting message, cdddr is a list of forms that are 
evaluated . 

usernamelst can be edited just like any other list, e.g., with editv . The file 
USERNAMEFILE, created by makeusernames , contains usernamelst along with an 
index block which contains for each user on usernamelst the address in the file 



This message can be suppressed by setting the variable sysoutgag to NIL 
(initially T). Alternatively, sysoutgag can be a list, in which case it is 
evaluated (if the user names are different), and thus the user can print 
his own message. 
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(i.e., byte position) of the start of his entry, greet then simply does an 
sfptr and a read . 

usernamelst contains an element for which the username is NIL, i.e., ah 
element of the form (NIL . forms), this is interpreted to mean that forms are 
evaluated regardless of user name. This feature can be used to "patch" an 
INTERLISP system when a bug is found, or to change some default for INTERLISP 
at a particular site, e.g., turn off DWIN, perform lowercase[T], etc. 
Individual user initialization will still be performed following this system 
initialization . 



22.66 



index for Section 22 



Page 
Numbers 



ADDSTATS[STATLST] NIL* 22.63 

AFTER (prog. asst. command) 22. 22, 26»34 

ALLPROP 22.55 

ALREADY UNDONE (typed by system) 22.22,59 

AND (In event specification) 22.13 

AND (in USE command) 22.14 

ARCHIVE (prog. a$st. command) ZZ.Z7 

ARCHIVEFN (prog. asst. variable/parameter) 22.27,33-34 

ARCHIVELST (prog, asst. variable/parameter) 22.44,53 

backtracking 22.60 

BEFORE (prog. asst. command) 22.22,26»34 

boll (In history event) 22.22,33,44,49,52 

BLKLIBRARYDEF (property name) 22.57,63 

CHANGtSLICE[N; HISTORY ;L] 22.8,54 

CLEARBUF[FILE;FLG] SUBR 22.30 

CONTIN (prog. asst. command) 22.34 

CONTINUE SAVING? (typed by system) 22.39.57 

control-D 22.30 

control-E 22.30 

control-U 22.32,50 

DFNFLG (system variable/parameter) 22.43,55 

DIR (prog. asst. command) 22.34 

DO (edit command) 22.31,61 

DO (prog. asst. command) 22.31 

DWIM 22.23 

DWIMWAIT (dwim variable/parameter) 22.39 

E (edit command) 22.62 

EDITDEFAULT 22.61 

EDITHISTORY (editor variable/parameter) 22.44,49,60-62 

ENTRY#[HIST;X] 22.54 

ERROR (property name) 22.24,45 

ESUBSTC X ; Y ; Z ;ERRORFLG jCHARFLG] 22 . 14 

event address ' 22.12-13 

event number 22.8,12,21,33,64 

event specification 22.11-14,19-21 

EXEC (prog. asst. command) 22.34 

F (in event address) 22.12 

FIX (prog. asst. command) 22.16-17,22 

FOR (in USE command) 22.14 

FORGET (prog. asst. command) , ,22.27,54 

format and use of history list 22.44-47 

FROM (in event specification) 22.13 

GREETtNAME;FLG] 22.64 

greeting and user initialization 22,64 

GROUP (property name) 22.45-46.52 

HELPCLOCK (system variable/parameter) 22.21,38 

HISTORY (property name) 22.45-46 

history commands 22.10-27 

history commands applied to history commands .... 22.19 

history commands that fail 22.20 

history list 22.6-14,44 

HISTORYCOMS (editor variable/parameter) 22.61 

HISTORYFIND 22.53 

HIST0RYSAVE[HIST0RY;ID;INPUT1;INPUT2;INPUT3;PR0PS] 22.11.44-46,62,61 

implementation of REDO, USE, and FIX 22.17-19 

IN (In USE command) 22.14 



INDEX. 22.1 



Page 
Numbers 



LISP (prog. asst. command) 

LISPXC L ISPXX ; LISPXID ; LISPXXMACROS ; LISPXXUSERFN ; 
LISPXFL6] 



LISPX/[X;rN;VARS] 

LISPXCOMS (prog. asst. variable/parameter) 

LISPXEVAL[LISPXFORM;LISPXID] 

LISPXFIND[HIST0RY;LINE;TYPE;;BACKUP;QUIETFLG] 

LISPXHIST (prog. asst. variable/parameter) 

LISPXmSTORY (prog. asst. variable/parameter) ... 

LISPXMISTORY (system variable/parameter) 

LISPXLINE (prog. asst. variable/parameter) ...... 

LISPXMACROS (prog. asst. variable/parameter) .... 

LISPXPRINT (property name) 

LISPXPRINT[X;Y;Z;NODOFLG] 

LISPXPRINTFLG (system variable/parameter) 

LISPXREADtFILE] 



LISPXREADFN (prog. asst. variable/parameter) .... 

LISPXREADPCFLG] 

LISPXSTATS[FLG] 

LISPXUNREAD[LST] 

LISPXUSERFN (prog. asst. variable/parameter) .... 

LISPXWATCH[STAT;N] 

MAKEUSERNAMES 

NAME (prog. asst. command) 

NEW/FN[FN] 

NLSETO[NLSETX] NL 

NO VALUE SAVED: (error message) 

NOBIND 

NOSAVE 

NOSUBSTFNS (prog. asst. variable/parameter) 

NOTHING SAVED (typed by system) 

PRINT (property name) 

PRINTHISTORY[ HISTORY ; LINE ; SKI PFN ;NOVALUES] 

programmer's assistant 

programmer's assistant and the editor 

programmer's assistant commands 

prompt character 

PROMPT#FLG (prog. asst. variable/parameter) 

PROMPTCHAR[ID;FLG;HIST] 

READBUF (prog. asst. variable/parameter) 

READLINE[LINE;LISPXFLG] 



REDO (prog, asst. command) 

REREADFLG (prog. asst. variable/parameter) 

RESET (typed by system) 

restoring input buffers 

RETRIEVE (prog. asst. command) 

RETRY (prog. asst. command) 

RPAQtRPAQXjRPAQY] NL 

RPAOO[X;Y] NL 

SAVESET[NAME;VALUE;TOPFLG;FLG] 

SIDE (property name) 

SNDMSG (prog. asst. command) 

SPELLINGS3 (dwim variable/parameter) .... 



22.34 

22.10-11.15-16,19-20,29, 
34-35,37-38,40-41, 
44-49,52,61-62 

22.40,58 

22.38 

22,52 

22.53,62 

22.45-46,66,59-60 

22.44,49,60-61 

22.62 

22.34 

22.34,49 

22.38,45 

22.37,45 

22.38 

22 . 10 , 1 9, 29 , 32 , 4 7-48 , 50 , 

61 
22.50 
22.50,61 
22.63-64 
22.51 

22.35,37,47,49 

22.63 
22.65 

22.14,22,25-26 

22.57 

22.59 

22.56 

22.43,55 

22.56-57 

22.58 

22.22,39 

22.45 

22.22,37-38,60 

22.1-48 

22.61 

22.10-31 

22.10,33,51 

22.33.51 

22.33.51.61 

22.50-51 

22.14,19,32,37,47-48,50, 
61 

22.14.17,22 
22.50,52 
22.43,56 
22.30 

22.22,26,34 
22.21-22 
22.43 
22.43 

22.40,43,65 

22.45-46,56-57,59,61 

22.34 

22.55 



INDEX. 22. 2 



Page 
Numbers 



statistics 22.63 

SUBSYSC F ILE /FORK ; INCOMFILE ;OUTCOMFILE ; 

ENTRYPOINTFLG] 22.34 

SY (prog. asst. command) 22.34 

SYSOUTGAG (system variable/parameter) 22.65 

TECO (prog. asst. command) 22.34 

TESTM0DE[FLG3 22.41 

TESTMODEFLG (prog. asst. variable/parameter) .... 22.41 

THRU (in event specification) 22.13 

time-slice (of history list) 22.8,54 

TO (in event specification) 22.13 

TYPE-AHEAD (prog. asst. command) 22.28-29 

UNDO (prog. asst. command) 22.13,22-23,43,58,61 

UNDO (edit command) 22.61 

undoing 22.5,38.55,62 

undoing (in editor) 22,62 

undoing DWIM corrections 22.23 

undoing out of order 22.23,42 

UNDOLISPX[LINE] 22.58 

UND0LISPX1[EVENT;FLG;DWIMCHANGES] 22.59 

UNDOLST (editor variable/parameter) 22.62 

UNDONE (typed by system) 22.22,59 

UND0NLSETQ[UND0F0RM;UND0FN] NL 22.59 

UNDOSAVE[UNDOFORM;HISTENTRY] 22.45-46,56 

unreading 22.10-11,18,51 

UNSET[NAME] 22.43,56 

USE (prog. asst. command) 22.14-15,17,22 

USE-ARGS (property name) 22.45 

USEREXECCLISPXID;LISPXXMACR0S;LISPXXUSERFN3 22.49 

USERNAME (prog. asst. variable/parameter) 22.65 

USERNAMELST (prog. asst. variable/parameter) 22.65-66 

VALUE (property name) 22.43,55-56 

VALUEOFCX] NL« 22.33,46,54 

!E (prog. asst. command) 22.31 

!E (edit command) ■. 22.31,61 

!F (prog. asst. command) 22.31 

!F (edit command) 22.31,61 

!N (prog. asst. command) 22.31 

!N (edit command) 22.31,61 

#0 (use in history commands) 22.18,50-51 

#UNDOSAVES (prog. asst. variable/parameter) 22.39,56-57,60 

$ (alt-mode) (prog. asst. command) 22.23-25 

SBUFS (alt-modeBUFS) (prog. asst. command) 22.30 

.....ATTENTION USER -- (typed by system) 22.65 

... (prog. asst. command) 22.21-22 

... (typed by system) 22.48 

/ functions 22.40,57-58 

/RPLNODE[X;A;D] 22.57 

= (in event address) 22.12 

?? (prog. asst. command) 22.21-22 

@ (in event specification) 22.14,53 

(3@ (in event specification) 22.14,27,53 

\ (in event address) 22.13 

(in event address) 22.12 



INDEX. 22. 3 



SECTION 23^ 
CLISP - CONVERSATIONAL LISP 



23.1 Introduction 

The syntax of LISP is very simple, in the sense that it can be described 
concisely, but not in the sense that LISP programs are easy to read or write! 
This simplicity of syntax is achieved by, and at the expense of, extensive use 
of explicit structuring, namely grouping through parenthesesizatlon. Unlike 
many languages, there are no reserved words in LISP such as IF, THEN, AND, OR, 
FOR, DO, BEGIN, END, etc., nor reserved characters like +, *. /. =» etc.^ 
This eliminates entirely the need for parsers and precedence rules in the LISP 
interpreter and compiler, and thereby makes program manipulation of LISP 
programs straightforward. In other words, a program that "looks at" other LISP 
programs does not need to incorporate a lot of syntactic Information. For 
example, a LISP interpreter can be written in one or two pages of LISP code 
([licCl], pp. 70-71). It is for this reason that LISP is by far the most 
suitable, and frequently used, programming language for writing programs that 
deal with other programs as data, e.g., programs that analyze, modify, or 
construct other programs. 



CLISP was designed and implemented by W. Teitelman. It is discussed in 
[Tei5]. 



except for parentheses (and period), which are used for indicating 
structure, and space and end-of-line, which are used for delimiting 
identifiers. 
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However, it is precisely this same simplicity of syntax that makes LISP 
programs difficult to read and write (especially for beginners). 'Pushing 
down' is something programs do very well, and people do poorly. As an example, 
consider the following two 'equivalent' sentences: 

"The rat that the cat that the dog that I owned chased caught ate the 
cheese." 

versus 

"I own the dog that chased the cat that caught the rat that ate the 

cheese . " 

Natural language contains many linguistic devices such as that illustrated in 
the second sentence above for minimizing embedding, because embedded sentences 
are more difficult to grasp and understand than equivalent non-embedded ones 
(even if the latter sentences are somewhat longer). Similarly, most high level 
programming languages offer syntactic devices for reducing apparent depth and 
complexity of a program: the reserved words and infix operators used in ALGOL- 
like languages simultaneously delimit operands and operations, and also convey 
meaning to the programmer. They are far more intuitive than parentheses. In 
fact, since LISP uses parentheses (i.e. lists) for almost all syntactic forms, 
there is very little information contained in the parentheses for the person 
reading a LISP program, and so the parentheses tend mostly to be ignored: the 
meaning of a particular LISP expression for people is found almost entirely in 
the words, not in the structure. For example, the following expression 

(COND (EQ N 0) 1) (T TIMES N FACTORIAL ((SUBl N))) 

is recognizable as FACTORIAL even though there are five misplaced or missing 
parentheses. Grouping words together in parentheses is done more for LISP's 
benefit, than for the programmer's. 

CLISP is designed to make INTERLISP programs easier to read and write by 
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permitting the user to employ various infix operators, IF-THEN-ELSE statements, 
FOR-DO-WHILE-UNLESS-FROM-TO-etc. expressions, which are automatically converted 
to equivalent INTERLISP expressions when they are first interpreted. For 
example, FACTORIAL could be written in CLISP: 

(IF N=0 THEN 1 ELSE N«(FACTORIAL N-1)) 

Note that this expression would become an equivalent CONO after it had been 
interpreted once, so that programs that might have to analyze or otherwise 
process this expression could take advantage of the simple syntax. 

There have been similar efforts in other LISP systems, most notably the NLISP 
language at Stanford [Smll]. CLISP differs from these in that it does not 
attempt to replace the LISP syntax so much as to augment it. In fact, one of 
the principal criteria in the design of CLISP was that users be able to freely 
intermix LISP and CLISP without having to identify which is which. Users can 
write programs, or type in expressions for evaluation, in LISP, CLISP, or a 
mixture of both. In this way, users do not have to learn a whole new language 
and syntax in order to be able to use selected facilities of CLISP when and 
where they find them useful. 

CLISP is implemented via the error correction machinery in INTERLISP (see 
Section 17). Thus, any expression that is well-formed from INTERLISP 's 
standpoint will never be seen by CLISP (i.e., if the user defined a function 
IF, he would effectively turn off that part of CLISP). This means that 
Interpreted programs that do not use CLISP constructs do not pay for its 
availability by slower execution time. In fact, the INTERLISP interpreter does 
not 'know' about CLISP at all. It operates as before, and when an erroneous 
form is encountered, the interpreter calls an error routine which in turn 
invokes the Do-What-I-Nean (DWIN) analyzer which contains CLISP. If the 
expression in question turns out to be a CLISP construct, the equivalent 
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INTERLISP form is returned to the interpreter. In addition, the original CLISP 
expression, is modified so that it becomes the correctly translated INTERLISP 
form. In this way, the analysis and translation are done only once. 

Integrating CLISP into the INTERLISP system (instead of, for example, 
implementing it as a separate preprocessor) makes possible Do-What-I-Nean 
features for CLISP constructs as well as for pure LISP expressions. For 
example, if the user has defined a function named GET-PARENT, CLISP would know 
not to attempt to interpret the form (GET-PARENT) as an arithmetic infix 
operation. (Actually, CLISP would never get to see this form, since it does 
not contain any errors.) If the user mistakenly writes (GET-PRAENT) , CLISP 
would know he meant (GET-PARENT), and not (DIFFERENCE GET PRAENT), by using the 
information that PRAENT is not the name of a variable, and that GET-PARENT is 
the name of a user function whose spelling is "very close" to that of 
GET-PRAENT. Similarly, by using information about the program's environment not 
readily available to a preprocessor, CLISP can successfully resolve the 
following sorts of ambiguities: 

1) (LIST X*FACT N), where FACT is the name of a variable, means 
(LIST (X»FACT) N). 

2) (LIST X*FACT N). where FACT is not the name of a variable but instead is 
the name of a function, means (LIST X*(FACT N)), i.e.. N is FACT'S 
argument . 

3) (LIST X*FACT(N)). FACT the name of a function (and not the name of a 
variable), means (LIST X"(FACT N)). 

4) cases (1),(2) and (3) with FACT misspelled! 

The first expression is correct both from the standpoint of CLISP syntax and 
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semantics and the change would be made without the user being notified. In the 
other cases, the user would be informed or consulted about what was taking 
place. For example, to take an extreme case, suppose the expression 
(LIST X*FCCT N) were encountered, where there was both a function named FACT 
and a variable named FCT. The user would first be ^sked if FCCT were a 
misspelling of FCT. If he said YES, the expression would be interpreted as 
(LIST (X*FCT) N).^ If he said NO, the user would be asked if FCCT were a 
misspelling of FACT, i.e., if he intended X«FCCT N to mean X*(FACT N). If he 
said YES to this question, the indicated transformation would be performed. If 
he said NO, the system would then ask if X*FCCT should be treated as CLISP, 
since FCCT is not the name of a (bound) variable.^ If he said YES, the 
expression would be transformed, if NO, it would be left alone, i.e., as 
(LIST X*FCCT N). Note that we have not even considered the case where X*FCCT is 
itself a misspelling of a variable name, e.g., a variable named XFCT (as with 
GET-PRAENT). This sort of transformation would be considered after the user 
said NO to X*FCCT N -> X«(FACT N). The graph of the possible interpretations 
for (LIST X*FCCT N) where FCT and XFCT are the names of variables, and FACT is 
the name of a function, is shown in Figure 23-1 below. 



Through this discussion, we speak of CLISP or DWIM asking the user. 
Actually, if the expression in question was typed in by the user for 
immediate execution, the user is simply informed of the transformation, on 
the grounds that the user would prefer an occasional misinterpretation 
rather than being continuously bothered, especially since he can always 
retype what he intended if a mistake occurs, and ask the programmer's 
assistant to UNDO the effects of the mistaken operations if necessary. For 
transformations on expressions in user programs, the user can inform CLISP 
whether he wishes to operate in CAUTIOUS or TRUSTING mode. In the former 
case (most typical) the user will be asked to approve transformations, in 
the latter, CLISP will operate as it does on type-in, i.e., perform the 
transformation after informing the user. 



This question is important because many INTERLISP users already have 
programs that employ identifiers containing CLISP operators. Thus, if 
CLISP encounters the expression A/B in a context where either A or B are 
not the names of variables, it will ask the user if A/B is intended to be 
CLISP, in case the user really does have a free variable named A/B. 
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FCCT- > FCT ? 




X«FCCT TREAT AS CLISP? 




FIGURE 23-1 
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The final states for the various terminal nodes shown in the graph are: 



1 : 


(LIST (TIMES X FCT) N) 


2: 


(LIST (TIMES X (FACT N))) 


3: 


(LIST XFCT N) 


4: 


(LIST (TIMES X FCCT) N) 


5; 


(LIST X*FCCT N) 



CLISP can also handle parentheses errors caused by typing 8 or 9 for '(' or 
')'. (On most terminals, 8 and 9 are the lower case characters for '(' and 
i.e., '(' and '8' appear on the same key, as do ')' and '9'.) For 
example, if the user writes N*8FACT0RIAL N-1, the parentheses error can be 
detected and fixed before the infix operator * is converted to the INTERLISP 
function TIMES. CLISP is able to distinguish this situation from cases like 
N'^BAX moaning (TIMES N 8 X), or N«8X, where 6X is the name of a variable, again 
by using information about the programming environment. In fact, by 
integrating CLISP with DWIN, CLISP has been made sufficiently tolerant of 
errors that almost everything can be misspelled! For example, CLISP can 
successfully translate the definition of FACTORIAL: 

(IFF N=0 THENNl ESLE N*8FACTT0RIALNN-1 ) 

to the corresponding CONO, while making 5 spelling corrections and fixing the 
parenthesis error^^ 

This sort of robustness prevails throughout CLISP. For example, the iterative 



CLISP also contains a facility for converting from INTERLISP back to CLISP, 
so that after running the above incorrect definition of FACTORIAL, the user 
could 'CLISPIFY' the now correct LISP version to obtain 
(IF N=0 THEN 1 ELSE N«(FACTORIAL N-l)). 
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statement permits the user to' say things like: 

FOR OLD X FROM M TO N 00 (PRINT X) WHILE (PRIMEP X) 

However, the user can also write OLD (X«-N), (OLD X«-N), (OLD (X«-M)), permute the 
order of the operators, e.g., DO PRINT X TO N FOR OLD X*-M WHILE PRIMEP X, omit 
either or both sets of parentheses, misspell any or all of the operators FOR, 
OLD, FROM, TO, 00, or WHILE, or leave out the word DO entirely! And, of 
course, he can also misspell PRINT, PRIMEP, M or N!^ 

CLISP is well integrated into the INTERLISP system. For example, the above 

iterative statement translates into an equivalent INTERLISP form using PROG, 

COND, GO, etc.^ When the Interpreter subsequently encounters this CLISP 

o 

expression, it automatically obtains and evaluates the translation. Similarly, 
the compiler "knows" to compile the translated form. However, if the user 
PRETTYPRINTs his program, at the corresponding point in his function, 
PRETTYPRINT "knows" to print the original CLISP. Similarly, when the user 
edits his program, the editor keeps the translation invisible to the user. If 



This expression should be self explanatory, except possibly for the 
operator OLD, which says X is to be the variable of iteration, i.e., the 
one to be stepped from N to M, but X is not to be rebound. Thus when this 
loop finishes execution, X will be equal to U*l, 



In this example, the only thing the user could not misspell is the first X, 
since it specifies the name of the variable of iteration. The other two 
instances of X could be misspelled. 



(PROG NIL 

(SETQ X M) 
S5LP(C0ND 

((OR (IGREATERP X N) 

(NOT (PRIMEP X))) 
(RETURN))) 
(PRINT X) 
(SETQ X (ADDl X)) 
(GO SSLP)) 



See page 23.30. for discussion of how translations are stored. 
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tho user modifies the CLISP, the translation is automatically discorded «nd 
recomputed the next time the expression is evaluated. 

In short, CLISP is not a language at all, but rather a system. It plays a role 
analagous to that of the programmer's assistant (Section 22). Whereas the 
programmer's assistant is an invisible intermediary agent between the user's 
console requests and the INTERLISP executive, CLISP sits between the user's 
progroms and the INTERLISP interpreter. 

Only a small effort has been devoted to defining the core syntax of CLISP. 
Instead, most of the effort has been concentrated on providing a facility which 
'makes sense' out of the input expressions using context information as well as 
built-in and acquired information about user and system programs. It has been 
said that communication is based on the intention of the speaker to produce an 
effect in the recipient. CLISP operates under the assumption that what the 
user said was intended to represent a meaningful operation, and therefore tries 
very hard to make sense out of it. The motivation behind CLISP is not to 
provide the user with many different ways of saying the same thing, but to 
enable him to worry less about the syntactic aspects of his communication with 
tho system. In other words, it gives the user a new degree of freedom by 
permitting him to concentrate more on the problem at hand, rather than on 
translation into a formal and unambiguous language. 

23.2 CLISP S y n tax 

Throughout CLISP, a non-atomic form, i.e., a list, can always be substituted 
for a variable, and vice versa, without changing the interpretation. For 
example, if the value of (FOO X) is A, and the value of (FIE Y) is B, then 
(LIST (FOO X)-»-(FIE Y)) has the same value as (LIST A+B). Note that the first 
expression consists of a list of Jour elements: the atom 'LIST', the list 
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•(FOO X)', the atom ' + and the list '(FIE X)', whereas the second expression, 
(LIST A+B), consists of a list of only two elements: the atom 'LIST* and the 
atom 'A+B'. Since (LIST (FOO X)+(FIE Y)) is indistinguishable from 
(LIST (FOO X)_+_(FIE Y)) because spaces before or after parentheses have no 
effect on the INTERLISP READ program, to be consistent, extra spaces have no 
effect on atomic operands either. In other words, CLISP will treat 
(LIST A-«-_B), (LIST A_+B), and (LIST A_+_B) the same as (LIST A+B). 



23.3 Infix Operators 

CLISP recognizes the arithmetic infix operators +, -, *, /, and t. These are 

converted to IPLUS, IDIFFERENCE (or in the case of unary minus, IMINUS), 

ITIMES, IQUOTIENT, and EXPT.^^ The usual precedence rules apply (although these 

12 

can be easily changed by the user), i.e., * has higher precedence than + so 
that A+B*C is the same as A+(B*C), and both * and / are lower than t so that 
2*Xt2 is the same as 2*(Xt2). Operators of the same precedence group from left 
to right, e.g., A/B/C is equivalent to (A/B)/C. Minus is binary whenever 
possible, i.e., except when it is the first operator in a list, as in (-A) or 
(-A), or when it immediately follows another operator, as in A*-B.^^ 



10 



11 



12 



13 



CLISP does not use its own special READ program because this would require 
the user to explicitly identify CLISP expressions, instead of being able to 
intermix INTERLISP and CLISP. 

The I in IPLUS denotes integer arithmetic, i.e., IPLUS converts its 
argumonts to integers, and returns an integer value. INTERLISP also 
contains floating point arithmetic functions as well as mixed arithmetic 
functions (see Section 13). CLISP contains a facility for declaring which 
type of nrithmetic is to be used, either by making a global declaration, or 
by separate declarations about individual functions or variables. See 
section on declarations, page 23.33. 

The complete order of precedence for CLISP operators is given in 
Figure 23-2. page 23.15. 

There are some do-what-I-mean features associated with Unary minus, as in 
(LIST -X Y). See section on operation, page 23.64. 
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iVote that grouping with parentheses can always be used to override the normal 
precedence grouping, or when the user is not sure how a particular expression 
will parse. 

1 5 

CLISP also recognizes as infix operators =, GT, LT, GE, and LE, as well as 
various predicates, e.g., MEMBER, AND, OR, EQUAL, etc.^^ AND is higher than OR, 
e.g., (X OR Y AND Z) is the same as (X OR (Y AND Z)), and both AND and OR are 
lower than the other infix operators, e.g., (X AND Y EQUAL Z) is the same as 
(X AND (Y EQUAL Z)). All of the infix predicates have lower precedence than 
INITERLISP forms, i.e., (FOO X GT FIE Y) is the same as ((FOO X) GT (FIE Y)), 
since it is far more common to apply a predicate to two forms, than to use a 
Boolean as an argument to a function, e.g. (FOO (X GT (FIE Y))). However, 
again, the user can easily change this. 

/Vote that only single character operators, e.g. +, ♦-, =, etc., can appear in 
interior of an atom. All other operators must be set off fro/n identifiers 
with spaces. For example, XLTY will not be recognized as CLISP. 



Note that •♦• in front of a number will disappear when the number is read, 
e.g., (rOO X +2) is indistinguishable from (FOO X 2). This means that 
(FOO X +2) will not be interpreted as CLISP, or be converted to 
(FOO (IPLUS X 2)). Similarly, (FOO X -2) will not be interpreted the same 
as (FOO X-2). To circumvent this, always type a space between the + or - 
and a number if an infix operator is intended, e.g., write (FOO X + 2). 



Greater Thnn, Less Than, Greater than or Equal to, and Less than or Equal 

to, respectively. GT, LT, GE, and LE are all affected by the same 

declarations as and *, with the initial default to use IGREATERP and 

ILESSP. 



Currently the complete list is MEMBER, MEMB, FMEMB, ILESSP, IGREATERP, 

LESSP, GRfATERP, FGTP, EQ, NEQ, EQP, EQUAL, OR, and AND. New infix 

operators can be easily added, as described in the section on CLISP 
internal conventions, page 23.68. 



In some cases, DWIM will be able to diagnose this situation as a run-on 
spoiling error, in which case after the atom is split apart, CLISP will be 
able to perform the indicated transformation. 
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: is an infix operator used in CLISP for extracting substructures from lists, 
e.g., X:3 specifies the 3rd element of X, (FOO Y)::2 specifies the second tail 
of (FOO Y), i.e., (CDDR (FOO Y)), and Z:l:2 Is the second element of the first 
element of Z, or (CADAR Z). Negative numbers may be used to indicate position 
counting from the end of a list, e.g., X:-l is the last element of X, or 
(CAR (LAST X)), X::-l is the last tail, i.e.. (LAST X).^^ 

n n n 



is used to indicate assignment, e.g., X»-Y translates to (SETQ X Y), In 
conjunction with : and ::, «- can also be used to perform a more general type of 
assignment, namely one involving structure modification. For example, X:2«-y 
means make the second element of X be Y, in INTERLISP terms 



The record facility, page 23.48, provides another way of extracting 
substructures by allowing the user to assign names to the various parts of 
the structure and then retrieve from or store into the corresponding 
structure by name. The pattern match facility, page 23.36, also can be 
used to extract substructure. : is also used to indicate both record and 
pattern match operations. 



The interpretation of negative numbers can be explained neatly in terms of 
edit commands: :-n returns what would be the current expression after 
executing the command -n, and ::-n returns what would be the current 
expression after executing -n followed by UP. 



If x does not have a value, and is not the name of one of the bound 
variables of the function in which it appears, spelling correction is 
attempted. However, since this may simply be a case of assigning an 
initial value to a new free variable, DWIN will always ask; for approval 
before making the correction. 



Note that an atom of the form X<-Y, appearing at the top level of a PROG, 
will not be recognized as an assignment statement because it will be 
interpreted as a PROG label by the INTERLISP interpreter, and therefore 
will not cause an error, so DWIM and CLISP will never get to see it. 
Instead, one must write (X«-Y). 
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(RPLACA (CDR X) Y). Negative numbers can also be used, e.g.. Y^.-Z^y. *■ 

is also used to indicate assignment in record operations, page 23.46, and 
pattern match operations, page 23.36. 

has different precedence on the left from on the right. On the left, is a 
"tight" operator, i.e., high precedence, so that A+B*-C is the same as A+(B*-C). 
On the right, *- has broader scope so that A«-B4C is the same as A^(B-«-C). 

On typein, $*-forra (alt-mode*-form) is equivalent to set the "last thing 
mentioned". For example, immediately after examining the value of 
LONGV/ARIABLENAHE, the user could set it by typing $«- followed by a form. 



23.4 Prefix Operators 



CLISP recognizes • and - as prefix operators. ' means QUOTE when it is the 
first character in an identifier, and is ignored when it is used in the 
interior of an Identifier. Thus, X='Y means (EQ X (OUOTE Y)), but X=CAN'T 
means (EQ X CAN'T), not (EQ X CAN) followed by (QUOTE T). This enables users 
to have variable and function names with ' in them (so long as the ' is not the 
first character). 



22 
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Note that the value of this operation is the value of rplaca , which is the 
corresponding node. 

The user can indicate he wants /rplaca and /rplacd used (undoable version 
of r p laca and r placd , see Section 22), or f rplaca and f rplacd (fast 
versions of rplaca and rplacd , see Section 5), by means of declarations 
(page 23.33). The initial default is for rplaca and rplacd . 



which translates to (RPLACA (NLEFT X 2) Y). 

i.e. is equivalent to (SETQ lastword form). See Section 17 



23.13 



Following all operators are ignored for the rest of the identifier, e.g., 
•«A moans (QUOTE *A), and 'X^Y means (QUOTE X«Y), not (EQ (QUOTE X) Y)."^^ 



On typein, '$ (i.e. 'alt-mode) is equivalent to (QUOTE value-of-lastword) (see 
Section 17). For example, after calling prettyprint on LONGFUNCTION, the user 
could move its definition to FOO by typing (MOVD •$ •FOO).'^'^ 

*^ means NOT. can negate a form, as in *( ASSOC X Y), or *X, or negate an 
infix operator, e.g., (A -GT B) is the same as (A LEQ B). Note that ^A«B means 
(EQ (NOT A) B). 



26 
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To write (EQ (QUOTE X) Y), one writes Y='X, or •X_=Y. This is one place 
where an extra space does make a difference. " 

Mot (MOVD S 'FOO). which would be equivalent to (MOVO LONGFUNCTION 'FOO), 
and would (probably) cause a U.B.A. LONGFUNCTION error, nor MOVO(S FOO), 
which would actually move the definition of S to FOO, since OWIN and the 
spelling corrector would never be invoiced. 
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Order of Precedence of CLISP operators 



(left precedence) 
- (unary), - 
t 

«. / 

*, - (binary) 

*- (right precedence) 

INTERLISP forms 

LT, 6T. EQUAL, MEMBER, etc. 

AND 

OR 

IF, THEN. ELSEIF, ELSE 
iterative statement operators 

Figure 23-2 



has a different left and right precedence, e.g., A+B^-C+D is the same as 
A+(B'^(C^D) ) . In other words, has minimal scope on the left and maximal 
scope on the right. 



When - negates an operator, e.g., --LT, the two operators are treated as 
a single operator whose precedence is that of the second operator. When 
negates a function, e.g., (^FOO X Y), it negates the whole form, i.e., 
(-(FOO X Y)). 
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23.5 Constructing Lists - the <,> operators 



Angle brackets are used in CLISP to indicate list construction. The appearance 
of a '<* corresponds to a '(' and indicates that a list is to be constructed 
containing all the elements up to the corresponding *>'. For example, <A B <C>> 
translates to (LIST A B (LIST C)). ! can be used to indicate that the next 
expression is to be inserted in the list as a segment, e.g., <A B ! C> 
translates to (CONS A (CONS B C)) and <! A ! B C> to (APPEND A B (LIST C)). M 
is used to indicate that the next expression is to be inserted as a segment, 
and furthermore, all list structure to its right in the angle brackets is to be 
physically attached to it, e.g., <!! A B> translates to (NCONCl A B), and 
<MA !B !C> to (NCONC A (APPEND B C)).^^ Note that <,!,!•, and > need not 
be separate atoms, for example, <A B ! C> may be written equally well as 
< A B !C >. Also, arbitrary INTERLISP or CLISP forms may be used within angle 
brackets. For example, one can write <FOO*-(FIE X) ! Y> which translates to 
(CONS (SETQ FOO (FIE X)) Y). CLISPIFY converts expressions in cons , list , 
append , nconc , nconcl, /nconc , and /nconcl into equivalent CLISP expressions 
using < , >, ! , and M . 

Note: angle brackets differ from other CLISP operators in that they act more 
like brackets than operators. For example, <A B 'O translates to 
(LIST A B (QUOTE C)) even though following all operators are ignored for the 
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The <,> operator was written by P.C. Jackson. 

Not (NCONC (APPEND A B) C), which would have the same value, but would 
attach C to B, and not attach either to A. 

The user can indicate /nconc or /nconcl be used instead of nconc and nconcl 
by declarations. 
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rest of the identifier. Note however that <A B '^O 0> is equivalent to 
(LIST A B (QUOTE C>) D). 



23.6 IF, THEN, ELSE 

CLISP translates expressions employing IF | THEN |ELSEIF| ELSE into equivalent 
conditional expressions. The segment between IFjELSEIF and the next THEN 
corresponds to the predicate of a CONO clause, and the segment between THEN and 
the next ELSE|ELSEIF as the consequent(s) . ELSE is the same as ELSEIF T THEN. 

IF, THEN, ELSE, and ELSEIF are of lower precedence than all infix and prefix 
operators, as well as INTERLISP forms, so that parentheses can be omitted 
between IFjELSEIF, and THEN. For example, (IF FOO X Y THEN --) is equivalent 
to (IF (FOO X Y) THEN — ).^^ Similarly, CLISP treats (IF X THEN FOO X Y ELSE 
as equivalent to (IF X THEN (FOO X Y) ELSE --) because it does not 'make 
sense' to evaluate a variable for effect. In other words, even if FOO were 
also the name of a variable, (COND (X FOO X Y)) doesn't make sense. 
Essentially, CLISP determines whether the segment between THEN and the next 
ELSE I ELSEIF corresponds to one form or several and acts accordingly. Thus, 
(IF THEN (FOO X) Y ELSE --) corresponds to a clause with two consequents. 
Similarly, (IF THEN FOO*-X Y ELSE --) corresponds to a clause with two 
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Only if a previous unmatched < has been seen, e.g. (PRINT 'A>B) will 
print the atom A>B. 

If FOO is the name of a variable, IF FOO THEN is translated as 
(COND (FOO --)) even if FOO is also the name of a function. If the 
functional interpretation is intended, FOO should bo enclosed in 
parentheses, e.g.. IF (FOO) THEN --. Similary for IF THEN FOO ELSEIF 

occasionally interacting with the user to resolve ambiguous cases. 
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consequents, and is equivalent to (IF THEN (FOCKX) Y ELSE ~-). 



23.7 Iterative Statements 

The following is an example of a CLISP iterative statement: 

(WHILE X*-( READ 'STOP DO (PRINT (EVAL X))) 

This statement says "READ an expression and set X to it. If X is not equal to 
the atom STOP, then evaluate X, print the result, and iterate." 

The i.s. (iterative statement) In its various forms permits the user to specify 
complicated iterative statements in a straightforward and visible manner. 
Rather than the user having to perform the mental transformations to an 
equivalent INTERLISP form using PROG, MAPC, MAPCAR, etc., the system does it 
for him. The goal was to provide a robust and tolerant facility which could 
"make sense" out of a wide class of iterative statements. Accordingly, the 
user should not feel obliged to read and understand in detail the description 
of each operator given below in order to use iterative statements. 

Currently, the following i.s. operators are implemented: FOR, BIND, OLD, IN, 
ON, FROM. TO, BY, WHEN, WHILE, UNTIL, UNLESS, COLLECT, JOIN, DO, SUM, COUNT, 
ALWAYS, NEVER, THEREIS, AS. FIRST, FINALLY, EACHTIME. Their function is 
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To write the equivalent of a singleton cond clause, i.e., a clause with a 
predicate but no consequent, write either nothing following the THEN, or 
omit the THEN entirely, e.g.. (IF (FOO X) THEN ELSEIF --) or 
(IF (FOO X) ELSEIF — ), meaning if (FOO X) is not NIL, it is the value of 
the cond. 

The statement translates to: 

(PROG NIL 5$LP (COND ((EQ (SETQ X (READ)) (QUOTE STOP)) (RETURN))) 
(PRINT (EVAL X)) (60 $$LP)) 
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explained below. New operators can be defined as described on page 23.28. 
Misspellings of operators are recognized and corrected. The order of 

o o 

appearance of operators is not important; CLISP scans the entire statement 
before it begins to construct the equivalent INTERLISP form. 



DO form 



specifies what is to be done at each iteration. DO with no 
other operator specifies an infinite loop. If some explicit 
or implicit terminating condition is specified, the value of 
the i.s. is NIL. Translate to MAPC or MAP whenever 
possible. 



COLLECT form 



like DO, except specifies that the value of form at each 
iteration is to be collected in a list, which is returned as 
the value of the i.s. when it terminates. Translates to 
MAPCAR or MAPLIST whenever possible. 



JOIN form 



like DO, except that the values are NCONCed. Translates to 
MAPCONC or MAPCON whenever possible. 



SUM form 



like DO, except specifies that the values of f orm at each 
iteration be added together and returned as the value of the 
i.s.. e.g. (FOR I FROM 1 TO 5 SUM It2) is equal to 



i+4+9+16+25. 
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DWIM and CLISP are invoked on iterative statements because car of the i.s. 
is not the name of a function, and hence generates an error. If the user 
defines a function by the same name as an i.s. operator, e.g. WHILE, TO, 
etc.. the operator will no longer have the CLISP interpretation when it 
appears as car of a form, although it will continue to be treated as an 
i.s. operator if it appears in the interior of an i.s. 

/NCONC, /MAPCONC, and /MAPCON are used when the declaration UNDOABLE is in 
ef f ect . 

iplus , f plus , or plus will be used for the translation depending on the 
declarations in effect. 
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COUNT pred 



like DO, except counts number of times that pred is true, 
and returns that count as its value. 



like 00, except returns T if the value of pred is non-NIL 
for all iterations (returns NIL as soon as the value of pred 
is NIL), e.g. (FOR X IN Y ALWAYS (ATOM X)) is the same as 
(EVERY Y (FUNCTION ATOM)). 

like ALWAYS, except returns T if the value of pred is neuer 
true, i.e. NEVER pred is the same as ALWAYS «pred. 

returns the first value of the i.v. for which pred is 
non-NIL, e.g. (FOR X IN Y THEREIS NUMBERP) returns the 
first number in Y, and is equivalent to 
(CAR (SOME Y (FUNCTION NUMBERP))).**^ 

DO. COLLECT, JOIN, SUM, ALWAYS, NEVER, and THEREIS are examples of a certain 
kind of i.s. operator called an i.s.type . The i.s.type specifies what is to be 
done at each iteration. Each i.s. must have one and only one i.s.type . The 
function i .s.type , page 23.28, provides a means of defining additional 
i .s. type s . 

FOR var specifies the. variable of iteration, or i.v., which is used 

in conjunction with IN, ON, FROM, TO, and BY. The variable 
is rebound for the scope of the i.s., except when modified 
by OLD as described below. 



ALWAYS pred 



NEVER pred 



THEREIS pred 



THEREIS returns the i.v. instead of the tail (as does the function some ) in 
order to provide an interpretation consistent with statements such as 
(FOR I FROM 1 TO 10 THEREIS --), where there is no tail. Note that 
(SOME Y (FUNCTION NUMBERP)) is equivalent to 
(FOR X ON Y THEREIS (NUMBERP (CAR X))). 
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FOR vars vars a list of variables, e.g., FOR (X Y Z) IN The first 

variable is the i.v., the rest are dummy variables. See 
BIND below. 

OLD var indicates var is not to be rebound, e.g., 

(FOR OLD X FROM 1 TO N DO — UNTIL --), 

BIND var, vars used to specify dummy variables, e.g., FOR (X Y Z) IN is 

equivalent to FOR X BIND (Y Z) IN --. BIND can be used 
without FOR. For example, in the i.s. shown on page 23.18, 
X could be made local by writing 
(BIND X WHILE X-( READ 'STOP. ..) . 

Note: FOR, OLD, and BIND variables can be initialized by using •-, e.g., 
(FOR OLD (X-form) BIND ( Y-form) . . . ) . 

IN form specifies that the i.s. is to iterate down a list with the 

i.v. being reset to the corresponding element at each 
iteration. For example, FOR X IN Y DO corresponds to 
(MAPC Y (FUNCTION (LAMBDA (X) --))). If no i.v. has been 
specified, a dummy is supplied, e.g., IN Y COLLECT CADR is 
equivalent to (MAPCAR Y (FUNCTION CADR)}. 

ON form same as IN except that the i.v. is reset to the 

corresponding tail at each iteration. Thus IN corresponds 
to MAPC, MAPCAR, and MAPCONC, while ON corresponds to NAP, 
MAPLIST, and MAPCON. 

IN OLD var specifies that the i.s. is to iterate down var , with var 

itself being reset to the corresponding tail at each 
iteration, e.g., after (FOR X IN OLD L DO ~- UNTIL --) 
finishes, L will be some tail of its original value. 
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IN OLD (var*-form) same as IN OLD var, except var is first set to value of 

form. 



ON OLD var 



same as IN OLD var except the i.v. is reset to the current 
value of var at each iteration, instead of to car[var3. 



ON OLD (var*-form) same as ON OLD var , except var is first set to value of 

form. 



WHEN pred 



provides a way of excepting certain iterations. For 
example, (FOR X IN Y COLLECT X WHEN NUMBERP X) collects only 
the elements of Y that are numbers. 



UNLESS pred 



same as WHEN except for the difference in sign, i.e., WHEN Z 
is the same as UNLESS ~Z. 



WHILE pred 



provides a way of terminating the i.s. WHILE pred evaluates 
pred before each iteration, and if the value is NIL, exits. 



UNTIL pred 



Same as WHILE except for difference in sign, i.e., 
WHILE PRED is equivalent to UNTIL '-PRED. 



UNTIL n 



n a number, equivalent to UNTIL (i.v. GT n). 



FROM form 



is used to specify an initial value for a numerical i.v. 
The i.v. is automatically incremented by 1 after each 
iteration (unless BY is specified). If no i.v. has been 
specified, a dummy i.v. is supplied and initialized, e.g., 
(COLLECT SORT FROM 2 TO 5) returns (1.414 1.732 2.0 2.236). 



TO form 



is used to specify the final value for a numerical i.v. If 
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FROM is not specified, the l.v. is initialized to 1 . If no 
i.v. has been specified, a dummy i.v. is supplied and 
initialized. If BY is not specified, the i.v. is 
automatically incremented by 1 after each iteration. When 
the i.v, is definitely being incremented^ i.e. either BY is 
not specified, or its operand is a positive number, the i.s. 
terminates when the i.v. exceeds the value of form (which Is 
reevaluated each Iteration) e.g., (FOR X FROM 1 TO 10 
is equivalent to (FOR X FROM 1 UNTIL (X GT 10) --). 

Similarly, when the i.v. is definitely being decremented the 
i.s. terminates when the i.v. becomes less than the value of 
form (see description of BY). 

BY X (with IN/ON) If IN or ON have been specified, the value of x determines 

the tail for the next iteration, which in turn determines 
the value for the i.v. as described earlier, i.e. the new 
i.v. is car of the tail for IN, the tail itself for ON. In 
conjunction with IN, the user can refer to the current tail 
within X by using the i.v., e.g. 

(FOR Z IN L BY (COOR Z) ...). At translation time, the name 
of the internal variable which holds the value of the 
current tail is substituted for the i.v. throughout x. For 
example, (FOR X IN Y BY (COR (MENB 'FOO (COR X))) COLLECT X) 
specifies that after each iteration, cdr of the current tail 
is to be searched for the atom FOO, and ( cdr of) this latter 
tail to be used for the next iteration. 



except when both the operands to TO and FROM are numbers, and TO's operand 
is less than FROM's operand, e.g. FROM 10 TO 1, in which case the i.v. is 
decremented by 1 after each iteration. In this case, the i.s. terminates 
when the i.v. becomes less than the value of form . 
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BY X (without IN/ON) If IN or ON have not been used, BY specifies how the 

l.v. itself is reset at each iteration. If FROM or TO have 
been specified, the i.v. is known to be numerical, so the 
new i.v. is computed by adding the value of x 
(which is reevaluated each iteration) to the current value 
of the i.v., e.g., (FOR N FROM 1 TO 10 BY 2 COLLECT N) makes 
a list of the first five odd numbers. 

If X Is a positive number, the i.s. terminates when the 
value of the i.v. exceeds the value of TO's operand. If x 
is a negative number, the i.s. terminates when the value of 
the i.v. becomes less than TO's operand, e.g. 
(FOR I FROM N TO M BY -2 UNTIL (I LT M) ...). Otherwise, 
the terminating condition for each iteration depends on the 
value of X for that iteration: if x < 0, the test Is whether 
the i.v. is less than TO's operand, if x > 0 the test is 
whether the i.v. exceeds TO's operand, otherwise if x=0, the 
i.s. terminates unconditionally.^^ 

If FROM or TO have not been specified, the i.v. is simply 
reset to the value of x after each iteration, e.g. 
(FOR I FROM N BY 2 ...) is equivalent to 

(FOR I-N BY (IPLUS 12) ...). 
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X itself, not its value, which in general CLISP would have no way of 
knowing in advance. 

A temporary variable is used so that x is only evaluated once. However, 
code for TO's operand appears twice in" the translation, even though it is 
evaluated only once. 
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FIRST form 



form is evaluated once before the first iteration, e.g. 
(FOR X Y Z IN L FIRST (FOO Y Z)), and FOO could be used 
to initialize Y and Z. 



FINALLY form form is evaluated after the i.s. terminates. For example, 

(FOR X IN L BIND Y*-0 00 (IF ATOM X THEN Y-Y+1) 
FINALLY (RETURN Y)) will return the number of atoms in L. 

EACHTIME form form is evaluated at the beginning of each iteration before, 

and regardless of, any testing. For example, consider (FOR I 
FROM 1 TO N DO (... (FOO I) ...) UNLESS (... (FOO I) ..-) 
UNTIL (... (FOO I) ...)). The user might want to set a 
temporary variable to the value of (FOO I) in order to avoid 
computing it three times each iteration. However, without 
knowing the translation, he would not know whether to put 
the assignment in the operand to 00, UNLESS, or UNTIL, i.e. 
which one would be executed first. He can avoid this 
problem by simply writing EACHTIME 0*-(FOO I). 

AS var is used to specify an iterative statement involving more 

than one iterative variable, e.g. 

(FOR X IN Y AS U IN V DO --) corresponds to mapZc . The i.s. 
terminates when any of the terminating conditions are met, 
e.g. (FOR X IN Y AS I FROM I TO 10 COLLECT X) makes a list 
of the first ten elements of Y, or however many elements 
there are on Y if less than 10. 



Except in the case of termination due to the appearance of a RETURN in some 
operand. See page 23.26. Thus in (FOR X IN Y THEREIS NUMBERP FINALLY --) 
the FINALLY operand would be evaluated if Y were exhausted, but not if a 
number was found. 
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The operand to AS, var, specifies the new i.v. 



For the 



remainder of the i.s 



• * 



or until another AS is encountered. 



all operators refer to the new i.v. 



For example, 



(FOR I FROM I TO Nl AS J FROM 1 TO N2 BY 2 



AS K FROM N3 TO 1 BY -1 terminates when I exceeds Nl, or 



J exceeds N2, or K becomes less than 1. 



After each 



iteration, I is incremented by 1, J by 2, and K by -1. 



Miscellaneous 

1. Lowercase versions of all i.s. operators are equivalent to the uppercase, 
e.g., (for X in Y ...). 

2. Each i.s. operator is of lower precedence than all INTERLISP forms, so 
parentheses around the operands can be omitted, and will be supplied where 
necessary, e.g., BIND (X Y Z) can be written BIND X Y Z, OLD (X«-form) as 
OLD X-form, WHEN (NUMBERP X) as WHEN NUMBERP X, etc. 

3. RETURN or GO may be used in any operand. RETURN means return from the i.s. 
(with the indicated value), not from the function in which the i.s appears. 
GO refers to a label elsewhere in the function in which the i.s. appears, 
except for (GO ITERATE), which means transfer control to the iterate 
portion of the loop, i.e. that part that resets the tail, increments the 
counter, or whatever, in preparation for the next iteration. The 
appropriate label will be substituted for ITERATE. 

4. In the case of FIRST, FINALLY, EACHTIME, or one of the i.s. types, e.g. DO, 
COLLECT, SUM, etc., the operand can consist of more than one form, e.g., 
COLLECT (PRINT X:l) X:2, in which case a PROGN is supplied. 

5. Each operand can be the name of a function, in which case it is applied to 
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the (last) i.v..^^ e.g., FOR X IN Y DO PRINT WHEN NUMBERP. is the 

same as FOR X IN Y DO (PRINT X) WHEN (NUMBERP X). Note that the i.v. need 
not be explicitly specified, e.g., IN Y 00 PRINT WHEN NUMBERP will work. 

Errors in Iterative Statements 

An error will be generated and an appropriate diagnostic printed if any of the 
following conditions hold: 

1. Operator with null operand, i.e. two adjacent operators, as in FOR X IN Y 
UNTIL DO 

2. Operand consisting of more than one form (except as operand to FIRST, 
FINALLY, or one of the i.s. types), e.g., FOR X IN Y (PRINT X) COLLECT --. 

3. Same operator appears twice. 

4. Both IN and ON used on same i.v. 

5. FROM or TO used with IN or ON on same i.v. 

6. More than one i.s. type, e.g. a 00 and a SUN. 

In 3, 4, or 5, an error is not generated if an intervening AS occurs. 
If an error occurs, the i.s. is left unchanged. 



For i.s. types, e.g. DO, COLLECT, JOIN, the function is always applied to 
the first i.v. in the i.s., whether explicity named or not. For example, 
(IN Y AS I FROM 1 TO 10 DO PRINT) prints elements on Y, not integers 
between 1 and 10. 



Note that this feature docs not make much sense for FOR, OLD, BIND, IN, or 
ON, since they "operate" before the loop starts, when the i.v. may not even 
be bound. 



In the case of BY in conjunction with IN, the function is applied to the 
current tail e.g., FOR X IN Y BY CDDR is the same as FOR X IN Y BY 

(CDDR X)... See page 23.23. 
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If no DO, COLLECT, JOIN or any of the other i.s. types are specified, CLISP will 
first attempt to find an operand consisting of more than one form, e.g., 
FOR X IN Y (PRINT X) WHEN ATOM X, and in this case will insert a 00 after the 
first form. (In this case, condition 2 is not considered to bo mot, and an 
error is not generated.) If CLISP cannot find such an operand, a warning 
message is printed: NO DO, COLLECT, OR JOIN: followed by the i.s. However, the 
i.s. is still translated, e.g. (WHILE form) can be used to execute form 
repeatedly until its value is NIL. 

Similarly, if no terminating condition is detected, i.e. no IN, ON, WHILE, 
UNTIL, TO, or a RETURN or GO, a warning message is printed: 
POSSIBLE NON-TERMINATING ITERATIVE STATEMENT: followed by the i.s. However, 
since the user may be planning to terminate the i.s. via an error, control^E, 
or a retf re m from a lower function, the i.s. is still translated. 

Defining Now Iterative Statement Operators 

The i.s. type specifies what is to be done at each iteration, e.g. collecting 
values on a list, adding numbers, searching for a particular condition, etc. 
Each i.s. can have one and only one i.s. type. The function i.s. type provides a 
means of defining new i.s. types. 

i .s.type[ name; form; inlt jval] name is the name of the i.s. type. form is the 

form to be evaluated at each iteration. In form SSVAL 
can be used to reference the value being assembled, 
I.V. to reference the current value of the i.v., and 
BODY to reference the body of the statement » i.e. 
name 's operand. 

For example, for COLLECT, form would be (SETQ SSVAL (NCQNCl SSVAL BODY)), for 
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SUM: ($$VAL*-$$VAUeODY).**' for NEVER: (AND BODY (RETURN NIL)), and for THEREIS: 
(AND BODY (RETURN I.V.)). 



init specifies the initial value for $$VAL, e.g. for 
SUM, init is 0. val specifies the value to be returned 
when the i.s. terminates. 

i.s. type is undoable. 

Examples : 

1) To define RCOLLECT, a version of COLLECT which uses cons instead of nconcl 
and then reverses the list of values: 

i.s.type[RCOLLECT;(SETQ SSVAL (CONS BODY SSVAL) ) ;NIL; (DREVERSE SSVAL)] 

2) To define TCOLLECT, a version of COLLECT which uses tconc ; 
i.s.type[TCOLLECT;(TCONC SSVAL BODY); (CONS); (CAR SSVAL)] 

3) To define PRODUCT: 

i.s. type[ PRODUCT ; ($SVAL-SSVAL«BODY) ; 1 ; SSVAL] 

i.s. typo performs the appropriate modifications to the property list for name , 
as well as for the lower case version of name, and also updates the appropriate 
spoiling lists. 

i.s. type can also be used to define synonyms for all i.s. operators, (not just 
those that are i.s. typos), by calling i .s.type with form an atom, e.g. 
i.s.typcC WHERE ;WHEN] makes WHERE be the same as WHEN. Similarly, following 



SSVAL+BODY is used instead of (IPLUS SSVAL BODY), so that the choice of 
function used in the translation, i.e. iplus , fplus , or plus , will be 
determined by the declarations then in effect. 



23.29 



i.s.typc[ISTHERE;THEREIS] one can write (ISTHERE ATOM IN Y), and following 
i.s.type[FIND;FOR] and i .s. type[SUCHTHAT;THEREIS], one can write 
(FIND X IN Y SUCHTHAT X MEMBER Z).^^ 

This completes the description of iterative statements. 



23.8 CLISP Translations 

The translation of infix operators and IF] THEN! ELSE statements are handled in 
CLISP by replacing the CLISP expression with the corresponding INTERLISP 
expression, and discarding the original CLISP, because (1) the CLISP expression 
is easily recomputable (by clispify ) , and (2) the INTERLISP expressions are 
simple and straightforward. In addition to saving the space required to retain 
both the CLISP and the INTERLISP, another reason for discarding the original 
CLISP is that it may contain errors that were corrected in the course of 
translation, e.g. the user writes FOCKFOOO:!, N*8F00 X), etc. If the original 
CLISP were retained, either the user would have to go back and fix these errors 
by hand, thereby negating the advantage of having DWIM perform these 
corrections, or else DWIN would have to keep correcting these errors over and 
over. 

Where (1) or (2) are not the case, e.g. with iterative statements, pattern 



In the current system, WHERE is synonymous with WHEN, SUCHTHAT and ISTHERE 
with THERE IS, and FIND with FOR. 



Note that cl ispify is sufficiently fast that it is practical for the user 
to configure his INTERLISP system so that all expressions are automatically 
£li5pi'^^^d immediately before they are presented to him. For example, he 
can define an edit macro to use in place of P which calls clispify on the 
current expression before printing it. Similarly, he can inform prettyprlnt 
to call clispify on each expression before printing it, etc. 
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matches, record expressions, etc. the original CLISP is retained (or a 

slightly modified version thereof), and the translation is stored elsewhere, 

usually in clispnrra y, a hash array. The interpreter automatically checks 

this array using gcthash when given a form car of which is not a function. 

Similarly, the compiler performs a gethash when given a form it does not 

recognize to see If it has a translation, which is then compiled instead of the 

form. Whenever the user changes a CLISP expresson by editing It, the editor 

automatically deletes its translation (if one exists), so that the next time It 

is evaluated or dwimified, the expression will be retranslated. The function 

2j)t and the edit commands PPT and CLISP: are available for examining 

translations, see page 23.75. Similarly, if prettytranf Ig Is T, prettyprlnt 

64 

will print the translations instead of the corresponding CLISP expression. 

clisparray is NIL,^^ translations are implemented instead by replacing the 
CLISP expression by an expression of the form 

(CLISPX__ translation . CLISP-expression),^^ e.g. (FOR X IN Y COLLECT (CAR X)) 



For example, the translation of X:5:3 is (CADDR (CAR (CDDDDR X))), which is 
difficult to read. Therefore, such expressions are handled by retaining the 
CLISP and storing the translation elsewhere, as described below. 
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The handling of translations for IF|THEN|ELSE statements is determined by 
the value of c llspif tran f Ig ♦ If T, the translations are stored elsewhere, 
and the (modified) CLISP retained as described below. If NIL, the 
corresponding COND replaces the IF|THEN|ELSE expression. The initial value 
of clispif tranf Ig Is NIL. 

Note that the user can always examine the translation himself by performing 
(GETHASH expression CLISPARRAY). 

clis parray is Initially NIL, and ^clisparray is its size. The first time a 
translation is performed, a hash array of this size is created. Therefore 
to disable clisparray , both it and #clisparray should be set to NIL. 

CLISP%_ is an atom consisting of the six characters C, L, I, S, P, and 
5poce, which must be preceded by the escape character % in order for It to 
be included as a part of an identifier. The intent was to deliberately 
make this atom hard to type so as to make it unlikely that it would 
otherwise appear in a user's program or data, since the editor and 
prettyprlnt treat It very specially, as described above. 
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would be replaced by 

(CLISPX_ (MAPCAR Y (FUNCTION CAR)) FOR X IN Y COLLECT (CAR X)). Both the 
editor nnd prottyprint know about CLISPX_ expressions and treat them specially 
by suppressing the translations: Prettyprint prints Just the CLISP 
(unless prettytranf lg =T, as described below), while the editor makes the 
translation completely invisible, e.g. if the current expression were the above 
CLISPX_ expression, F MAPCAR would fail to find the MAPCAR, and (3 ON) would 
replace IN with ON, i.e. the editor operates as though both the CLISPX_ and the 
MAPCAR were not there. As with translations implemented via clisparray , if the 
CLISP expression is changed by editing it, the translation is automatically 
deleted. 

CLISP%_ expressions will interpret and compile correctly: CLISPX_ is defined as 
an nlambda nospread function with an appropriate compiler macro. Note that if 
the user sets clisparray to NIL, he can then break, trace, or advise CLISPX_ to 
monitor the evaluation of iterative statements, pattern matches, and record 
operations. This technique will work even if clisparray was not NIL at the time 
the expressions were originally translated, since setting clisparray to NIL 
will effectively delete the translations, thereby causing the CLISP expressions 
to be retranslated when they are first encountered. Note that if the user only 
wishes to monitor the CLISP in a certain function, he can accomplish this by 
embedding its definition in (RESETVAR CLISPARRAY NIL *). 

If a CLISPX_ expression is encountered and clisparray is not NIL, the 
translation is transferred to the hash array, and the CLISPX_ expression 
replaced by just the CLISP. Setting prettytranf Ig to CLISPX_ causes 
prettyprint to print CLISP expressions that have been translated in the form of 
(CLISPX_ translation . CLISP-expresslon), even if the translation is currently 
stored in clisparray . These two features together provide the user with a way 
of dumping CLISP expressions together with their translations so that when 
reloaded (and run or dwimified), the translations will automatically be 
transferred to clisparray . 
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In summary, if prettytranf lg =NIL, only the CLISP is printed (used for producing 
listings). If prettytranf lg =T. only the translation is printed (used for 
exporting programs to systems that do not provide CLISP, and to examine 
translations for debugging purposes). If prettytranf lg =CLISP% , an expression 
of the form (CLISPX_ translation . CLISP) is printed, (used for dumping both 
CLISP and translations). The preferred method of storing translations is in 
clisparray , so that if any CLISPX__ expressions are converted while clisparray 
is not NIL, they will automatically be converted so as to use clisparray . If 
clisparray=NIL, they will be left alone, and furthermore, new translations will 
be implemented using CLISPX_ expressions. 

23.9 Declarations 

Declarations are used to affect the choice of INTERLISP function used as the 
translation of a particular operator. For example, A-f-B can be translated as 
either (IPLUS A B), (FPLUS A B). or (PLUS A B), depending on the declaration in 
effect. Similarly X:l-Y can mean (RPLACA X Y), (FRPLACA X Y), or 
(/RPLACA X Y), and <!!A B> either (NCONCl A B) or (/NCONCl A B). The table 
below gives the declarations available in CLISP, and the INTERLISP functions 
they indicate. The choice of function on all CLISP transformations are 
affected by these declarations, i.e. iteraiue statements, pattern matches, 
record operations , as mell as infix and prefix operators. 

The user can make (change) a global declaration by calling the function 
CLISPOEC and giving it as its argument a list of declarations, e.g., 
(CLISPDCC (QUOTE (FLOATING UNDOABLE))). Changing a global declaration does not 
affect the speed of subsequent CLISP transformations, since all CLISP 



Note that makefile will reset prettytranf Ig to T, using resetvar , when 
called with the option NOCLISP. 
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transformation are table driven (i.e. property list), and global declarations 
aro accomplished by making the appropriate internal changes to CLISP at the 
time of the declaration. If a function employs local declarations (described 
below), there will be a slight loss in efficiency owing to the fact that for 
each CLISP transformation, the declaration list must be searched for possibly 
relevant declarations. 

Declarations are implemented in the order that they are given, so that later 
declarations override earlier ones. For example, the declaration FAST 
specifies that FRPLACA, FRPLACO, FMEMB, and FLAST be used in place of RPLACA, 
RPLACD, MEMB, and LAST; the declaration RPLACA specifies that RPLACA be used. 
Therefore, the declarations (FAST RPLACA RPLACO) will cause FMEMB, FLAST, 
RPLACA, and RPLACO to be used. 

The initial global declaration is INTEGER and STANDARD. 
Table of Declarations 

Declaration INTERLISP functions to be used 

INTEGER or FIXED IPLUS, IMINUS, IDIFFERENCE, ITIMES, IQUOTIENT, ILESSP, 



IGREATERP 



FLOATING 



FPLUS, FMINUS, FDIFFERENCE, FTIMES, FQUOTIENT, LESSP, 

FGTP 



MIXED 



PLUS, MINUS, DIFFERENCE, TIMES, QUOTIENT, LESSP, 
GREATERP 



FAST 



FRPLACA, FRPLACD, FMEMB, FLAST, FASSOC 



UNDOABLE 



/RPLACA, /RPLACD, /NCONC, /NCONCl, /MAPCONC, /MAPCON 



STANDARD 



RPLACA, RPLACO, MEMB, LAST, ASSOC, NCONC, NCONCl, 
MAPCONC, MAPCON 



RPLACA, RPLACD, 
/RPLACA, ... 



corresponding function 
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Local 



Declarations 



The user can also make declarations affecting a selected function or functions 
by inserting an expression of the form (CLISP: . declarations) immediately 
following the argument list, i.e., as CADDR . of the definition. Such local 
declarations take precedence over global declarations. Declarations affecting 
selected variables can be indicated by lists, where the first element is the 
name of a variable, and the rest of the list the declarations for that 
variable. For example, (CLISP: FLOATING (X INTEGER)) specifies that in this 
function integer arithmetic be used for computations involving X, and floating 
arithmetic for all other computations.^^ The user can also make local record 
declarations by inserting a record declaration, e.g. (RECORD »), 
(ARRAYRECORD --), etc.. In the local declaration list. Local record 
declarations override global record declarations for the function in which they 
appear. Local declarations can also be used to override the global setting of 
certain DWIM/CLISP parameters effective only for transformations within that 
function, by including in the local declaration an expression of the form 
(variable = value), e.g. ( PATVARDEFAULT » QUOTE). 

The CLISP: expression is converted to a comment of a special form recognized by 
CLISP. Whenever a CLISP transformation that is affected by declarations is 
about to be performed in a function, this comment will be searched for a 
relevant declaration, and if one is found, the corresponding function will be 
used. Otherwise, if none are found, the global declaration(s) currently in 
effect will be used. 



'involving' moans where the variable itself is an operand. For example, 
with the declaration (FLOATING (X INTEGER)) in effect, (FOO X)+(FIE X) 
would translate to FPLUS, i.e., use floating arithmetic, even though X 
appears somewhere inside of the operands, whereas X+(FIE X) would translate 
to IPLUS. If there are declarations involving both operands, e.g. X4-Y, 
with (X FLOATING) (Y INTEGER), whichever appears first in the declaration 
list will be used. 
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Local declarations are effective in the order that they are glvcn» so that 
later declarations can be used to override earlier ones, e.g. 
(CLISP: FAST RPLACA RPLACD) specifies that FMEMB, FLAST. RPLACA, and RPLACO be 
used. An exception to this is that declarations for specific variables take 
precedence of general, function-wide declarations, regardless of the order of 
appearance, as in (CLISP: (X INTEGER) FLOATING). 

Clispify also checks the declarations in effect before selecting an infix 
operator to ensure that the corresponding CLISP construct would in fact 
translate back to this form. For example, if a FLOATING declaration is in 
effect, clispify will convert (FPLUS X Y) to X+Y, but leave (IPLUS X Y) as is. 
Note that if (FPLUS X Y) is CLISPIFYed while a FLOATING declaration is under 
effect, and then the declaration is changed to INTEGER, when X+Y is translated 
back to INITERLISP, it will become (IPLUS X Y). 

23.10 The Pattern Match Compiler ^^ 

CLISP contains a fairly general pattern match facility. The purpose of this 
pattern match facility is to make more convenient the specifying of certain 
tests that would otherwise be clumsy to write (and not as intelligible), by 
allowing the user to give instead a pattern which the datum is supposed to 
match. Essentially, the user writes "Does the (expression) X look like 
(the pattern) P?" For example, X:(& 'A '6) asks whether the second element 
of X is an A, and the last element a B. The implementation of the matching is 
performed by computing (once) the equivalent INITERLISP expression which will 
perform the indicated operation, and substituting this for the pattern, and not 
by invoking each time a general purpose capability such as that found in FLIP 



The pattern match compiler was written by L. N. Nasinter. 
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or PLANNER. For example, the translation of X:(& *A 'B) is; 
(AND (EO (CADR X) (QUOTE A)) (EQ (CAR (LAST X)) (QUOTE B))). Thus the CLISP 
pattern match facility is really a Pattern Compiler, and the emphasis in its 
design and implementation has been more on the efficiency of object code than 
on generality and sophistication of its matching capabilities. The goal was to 
provide a facility that could and would be used even where efficiency was 
paramount, e.g. in inner loops. As a result, the CLISP .pattern match facility 
does not contain (yet) some of the more esoteric features of other pattern 
match languages, such as repeated patterns, disjunctive and conjunctive 
patterns, recursion, etc. However, the user can be confident that what 
facilities it does provide will result in INTERLISP expressions comparable to 
those he would generate by hand.^^ 

The syntax for pattern match expressions is formrpattern , where pattern is a 
list as described below. As with iterative statements, the translation of 
patterns, i.e., the corresponding INTERLISP expressions, are stored in 
clisparray , a hash array, as described on page 23.30. The original expression, 
form '.pattern. Is replaced by an expression of the form 
(MATCH form WITH pattern). CLISP also recognizes expressions input in this 
form. 

f oi"!^ appears more than once in the translation, and it is not either a 
variable, or an expression that is easy to (re)compute, such as (CAR Y), 
(CODR Z), etc., a dummy variable will be generated and bound to the value of 
form so that form is not evaluated a multiple number of times. For example, 
the translation of (FOO X):($ 'A $) is simply (MEMB (QUOTE A) (FOG X)), while 
the translation of (FOO X):('A 'B --) is: 



Wherever possible, already existing INTERLISP functions are used in the 
translation, e.g., the translation of (S 'A S) uses HEMB, (S ('A S) S) uses 
ASSOC. etc. 
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[PROG ($$2) (RETURN 

(AND (KQ (CAR (SETQ SS2 (FOO X))) 
(QUOTE A)) 
(EQ (CAOR $52) (QUOTE B]. 

In the interests of efficiency, the pattern match compiler assumes that all 
lists end in NIL, i.e. there are no LISTP checks inserted in the translation to 
check tails. For example, the translation of X:('A & — ) is 
(AND (EO (CAR X) (QUOTE A)) (CDR X)), which will match with (A B) as well as 
(A . B). Similarly, the pattern match compiler does not insert LISTP checks on 
elements, e.g. X:(('A --) --) translates simply as (EQ (CAAR X) (QUOtE A)), and 
X:(($l $1 --) --) as (CODAR X).^^ Note that the user can explicitly insert 
LISTP checks himself by using @, as described on page 23.40, e.g. 
X:(($l SI --)@LISTP --) translates as (AND (LISTP (CAR X)) (CDOAR X)). 



Pattern Elements 

A pattern consists of a list of pattern elements. Each pattern element is said 
to match either an element of a data structure or a segment, (cf. the editor's 
pattern matcher, matches any arbitrary segment of a list, while & or a 

subpattern match only one olemGut of a list.) Those patterns which may match a 
segment of a list are called SEGMENT patterns; those that match a single 
element are called ELEMENT patterns. 



The insertion of LISTP checks for elements is controlled by the variable 
pat llstpchnck . When pa tlistpcheck is T, LISTP checks are inserted, e.g. 
X:(('A --) --) translates as: 

(AND (LISTP X) (LISTP (CAR X)) (EQ (CAAR X) (QUOTE A))). 
patlistpcheck is initially NIL. Its value can be changed within a 
particular function by using a local declaration, as described on page 
23.35. 
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Element Patterns 



There are several types of element patterns, best given by their syntax: 



PATTERN 



NEANING 



Si, or & 



matches an arbitrary element of a list 



expression 



matches only an element which is equal to the given 
expression e.g., 'A,^^ '(A B). 



sform 



matches only an element which is equal to the value of form, 
e.g., «X, "(REVERSE Y). 



==form 



same as but uses an e^ check instead of equal 



atom 



treatment depends on setting of patvardefault . 

patvardefault is ' or QUOTE, same as 'atom. 
If patvardefault is « or EQUAL, same as satom. 
If patvardefault is =s or EQ, same as ssatoro. 
If patvardefault is or SETQ, same as atom«-&. 
patvardefault is initially a.^^ 



Note: numbers and strings are always interpreted as though patvardefault were 
= , regardless of its setting. E^, memb . and assoc are used for comparisons 
involving small integers. 



62 



63 



DIQMZ* assoc are automatically used in the translation when the 

quoted expression is atomic, otherwise equal , member , and sassoc . 

patvardcf ault can be changed within a particular function by using a local 
declaration, as described on page 23.35. 
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{pattern^ ... pattern^) n > 1 matches a list which matches the given 

patterns, e.g., (& &), (*- 'A). 

elemGnt-pattorn^function-object matches an element if the elomont-pattern 

matches it, and the function-object (name of a function or a 
LAMBDA expression) applied to that element returns non-NIL, 
e.g. &@NUMBERP matches a number, ('A --)@F00 matches a list 
whose first element is A, and for which FOO applied to that 
list is non-MIL.^^ 



matches any arbitrary element. If the entire match 
succeeds, the element which matched the * will be returned 
as the value of the match. 



Note: normally, the pattern match compiler constructs an expression whose value 
is guaranteed to be non-NIL if the match succeeds and NIL if it fails. 
However, if a * appears in the pattern, the expression generated will either 
return NIL if the match fails, or whatever matched the * even though that may 
be NIL. For example, X:('A « --) translates as 

(AND (EQ (CAR X) (QUOTE A)) (GDR X) (CADR X)). 

^element-pattern matches an element if the element is not matched by 

element-pattern, e.g. -'•A, -^aX, -'( — 'A — ). 



For 'simple' tests, the function-object is applied before a match is 
attempted with the pattern, e.g. ((-- 'A --)0LISTP translates as 

(AND (LISTP (CAR X)) (MEMO (QUOTE A) (CAR X))), not the other way around. 
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Segment Patterns 

or matches any i»egment of a list (including one of zero 

length). 

The difference between $ and is in the type of search they generate. For 
example, X:(S 'A «B S) translates as (EQ (CADR (NEMB (QUOTE A) X)) (QUOTE 6)). 
whereas X:(-- 'A 'B S) translates as: [SOME X (FUNCTION (LAMBDA (SS2 SSI) 
(AND (EQ $$2 (QUOTE A)) (EQ (CADR $51) (QUOTE B]. Thus, a paraphrase of 
($ 'A 'B $) would be "Is the element following the first A a B?", whereas a 
paraphrase of (-^ 'A 'B S) would be "Is there any A immediately followed by a 
B?" Note that the pattern employing $ will result in a more efficient search 
than that employing However, (S 'A 'B S) will not match with 

(X Y Z A M N 0 A B C), but (— 'A 'B $) will. 

Essentially, once a pattern following a S matches, the S never resumes 
searching, whereas — produces a translation that will always continue 
searching until there is no possibility of success. However, if the pattern 
match compiler can deduce from the pattern that continuing a search after a 
particular failure cannot possibly succeed, then the translations for both 
and S will be the same. For example, both X:($ 'A $3 S) and (-- 'A S3 —) 
translate as (CDDDR (MEMB (QUOTE A) X)), because if there are not three 
elements following the first A, there certainly will not be three elements 
following subsequent A's, so there is no reason to continue searching, even for 
--. Similarly, (S 'A S 'B S) and (-- 'A — 'B --) are equivalent. 

S2, S3, etc. matches a segment of the given length. Note that SI is not 

a segment pattern. 

! element-pattern matches any segment which the given element pattern would 

match as a list. For example, if the value of FOG is 
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(A B C) !-F00 will match the segment ...ABC... etc. 
Note that !" is permissible and means Value-of-match«-$, e.g. 
X:($ 'A !«) translates to (COR (NEMB (QUOTE A) X)). 

Note: since ! appearing in front of the last pattern specifies a match with 
some tail of the given expression, it also makes sense in this case for a ! to 
appear in front of a pattern that can only match with an atom, e.g.* (S2 ! 'A) 
means match if cddr of the expression is the atom A. Similarly, X:(S ! *A} 
translates to (EQ (COR (LAST X)) (QUOTE A)). 

!atom treatment depends on setting of patvardefault . If 

patvardefault is ' or QUOTE, same as ! 'atom (see above 
discussion). If patvardefault is s or EQUAL, same as 
Isatom. If patvardefault is == or EQ, same as Issatom. If 
patvardefault is or SETQ, same as atom*-$. 

fie: 

The atom '.' is treated exactlu like !. In addition, if a 
pattern ends in an atom, the '.' is first changed to !, 
e.g., (51 . A) and (SI ! A) are equivalent, even though the 
atom '.' does not explicitly appear in the pattern. 

Segment-pattern@function-object matches a segment if the segment-pattern 

matches it, and the function object applied to the 
corresponding segment (as a list) returns non-NIL, e.g. 



With one exception, namely '.' preceding an assignment does not have the 
special interpretation that ! has preceding an assignment (see page 
23.43). For example, X:('A . FOO«-'B) ' translates as: 

(AND (EQ (CAR X) (QUOTE A)) (EQ (COR X) (QUOTE B)) (SETQ FOO (COR X))), 
but X:('A ! FOO-'B) translates as: 

(AND (EQ (CAR X) (QUOTE A)) 

(NULL (CDDR X)) 

(EQ (CADR X) (QUOTE B)) 

(SETQ FOO (CDR X))). 
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(S@CDDR 'D $) matches (A B C 0 E) but not (ABO E), since 
CDDR of (A B) is NIL. 

Note: an 0 pattern applied to a segment will require computing the 
corresponding structure (with Idiff ) each time the predicate is applied (except 
when the segment in question is a tail of the list being matched). 

Assignments 

Any pattern element may be preceded by a variable and a '^'. meaning if the 
match succeeds (i.e., everything matches)* the variable given is to be set to 
what matches that pattern element. For example, if X = (A 8 C D E), 
X:($2 Y*-$3) will set Y to (C 0 E). Assignments are not performed until the 
entire match has succeeded. Thus, assignments cannot be used to specify a 

aft 

search for an element found earlier in the match, e.g. Xi(Y*-$l -Y — ) will 
not match with (A A B C . . . ) .^^ This type of match is achieved by using 
place-markers, described below. 

If the variable is preceded by a !, the assignment is to the tai{ of the list 
as of that point in the pattern, i.e. that portion of the list matched by the 
remainder of the pattern. For example, if X is (A B C D E), X:($ !Y*-'C '0 S) 
sets Y to (C D E), i.e. cddr of X. In other words, when ! precedes an 
assignment, it acts as a modifier to the •-, and has no effect whatsoever on the 
pattern itself, e.g. X:('A 'B) and X:('A !FOO«-*B) match identically, and in 
the latter case, FOO will be set to COR of X. 



The translation of this pattern is: 
(COND ((AND (CDR X) (EQUAL (CAOR X) Y)) 

(SETQ Y (CAR X)) 

T)). 

The AND is because if Y is NIL, the pattern should match with (A NIL), but 
not with just (A). The T is because (CAR X) might be NIL. 

unless, of course, the value of Y was A before the match started. 
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Note: **-pattern-element and !*«-pattern-element are acceptable, e.g. 

X:(S 'A ••-(•B --) --) translates as: 

[PROG (SS2) (RETURN 

(AND (EQ (CAADR (SETQ SS2 (MEMB (QUOTE A) X))) 
(QUOTE B)) 
(CADR SS2] 

PlacG-markcrs 

Variables of the form #n, n a number, are called place-markers, and are 
interpreted specially by the pattern match compiler. Place-markers are used in 
a pattern to mark or refer to a particular pattern element. Functionally, they 
are used like ordinary variables, i.e. they can be assigned values, or used 
freely in forms appearing in the pattern, e.g. X:(#1«-S1 "(AOOl #1)) will match 
the list (2 3). However, they are not really variables in the sense that they 
are not bounds nor can a function called from within the pattern expect to be 
able to obtain their values. For convenience, regardless of the setting of 
patvardefault , the first appearance of a defaulted place-marker is interpreted 
as though patvardefault were ••. Thus the above pattern could have been written 
as X:(#l =:(A001 #1)). Subsequent appearances of a place-marker are interpreted 
as though patvardefault were =. For example, X:(#l #1 --) is equivalent to 
X:(#1-S1 =#1 — ), and translates as (AND (COR X) (EQUAL (CAR X) (CAOR X)).^* 

Replacements 

Any pattern element may be followed by a and a form, meaning if the match 
succoods, the part of the data that matched is to be replaced (e.g., with 



Just (EQUAL (CAR X) (CADR X)) would incorrectly match with (NIL). 
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RPLACA or RPLACO)^*' with the value of <forin>. For example, if X =(A B C 0 E), 
X:(S 'C $1«-Y SI) will replace the fourth element of X with the value of Y. As 
with assignments, replacements are not performed until after it is determined 
that the entire match toill be successful . 

Replacements involving segments splice the corresponding structure into the 
list being matched, e.g. if X is (A B C 0 E F) and FOO is (12 3), after the 
pattern ('A S^FOO '0 S) is matched with X, X will be (A 1 2 3 D E F), and FOO 
will bo §3 to COR of x» i.e. (1 2 3 D E F). 

« « n 

Note that ($ FOO«-FIE $) is ambiguous, since it is not clear whether FOO or FIE 
is the pattern element, i.e. whether specifies assignment or replacement. 
For example, if patvardofault is =, this pattern can be interpreted as 
($ FOO«-=FIE S). meaning search for the value of FIE, and if found set FOO to 
it, or (S =FOO*-FIE S) meaning search for the value of FOO, and if found, store 
the value of FIE into the corresponding position. In such cases, the user 
should disambiguate by not using the patvardofault option, i.e. by specifying ' 
or a . 



The user can indicate he wants /rplaca and /rplacd used, or frplaca and 
f rplacd, by means of declarations. The initial default is for rplaca and 
rplacd . 
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R econstruction 

The user can specify a value for a pattern match operation other than what is 

returned by the match by writing after the pattern => followed by another form, 

e.g. X:(FOO»-$ 'A --) => (REVERSE FOO)/^ which translates as: 

[PROG ($$2) (RETURN 

(CONO ((SETO S$2 (MEMB (QUOTE A) X)) 
(SETO FOO (LDIFF X $2)) 
(REVERSE FOO]. 

Place-markers in the pattern can be referred to from within form , e.g. the 
above could also have been written as X:(!#l 'A )->(REVERSE #1). If -> is 
used in place of =>» the expression being matched is also physical ly changed to 
the value of form . For example, X:(#l 'A !#2) -> (CONS #1 #2) would remove the 
second element from X, if it were equal to A. 

In general, forml :pattern->form2 is translated so as to compute form2 if the 
match is successful, and then smash its value into the first node of forml . 
However, whenever possible, the translation does not actually require form2 to 
be computed in its entirety, but instead the pattern match compiler uses form2 
as an indication of what should be done to forml . For example, 
X:(#l 'A !#2) -> (CONS #1 #2) translates as: 
(AND (EQ (CADR X) (QUOTE A)) (RPLACO X (CDOR X))). 



The original CLISP is replaced by an expression of the form 
(MATCH forml WITH pattern => form2). CLISP also recognizes expressions 
Input In this form. 
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Examples 



X:(-- 'A --) matches any arbitrary segment. 'A matches only an 

A, and the 2nd again matches an arbitrary segment; 
thus this translates to (MEMB (QUOTE A) X). 

X:(-- 'A) Again, matches an arbitrary segment; however, since 

there is no after the 'A, A must be the last element 
of X. Thus this translates to: 

(EQ (CAR (LAST X)) (QUOTE A)). 

X:('A 'B >- 'C $3 --) CAR of X must be A, and CADR must be B, and there must 

be at least three elements after the first C, so the 

translation is: 

(AND (EQ (CAR X) (QUOTE A)) 
(EQ (CADR X) (QUOTE B)) 
(CDODR (MEMB (QUOTE C) (CDDR X)))) 

X:(('A 'B) 'C Y»-$l $) Since ('A 'B) does not end in $ or (COOAR X) must 

be NIL. 
(COND 

((AND (EQ (CAAR X) (QUOTE A)) 
(EQ (CADAR X) (QUOTE B)) 
(NULL (CDDAR X)) 
(EQ (CADR X) (QUOTE C)) 
(CDDR X)) 
(SETQ Y (CADDR X)) 
T)) 

X:(#l 'A $ *B 'C #1 S) #1 is implicitly assigned to the first element in the 

list. The $ searches for the first B following A. This 

B must be followed by a C, and the C by an expression 

equal to the first element. 

[PROG ($$2) (RETURN 

(AND (EQ (CADR X) (QUOTE A)) 

(EQ [CADR (SETQ SS2 (MEMB (QUOTE B) (ODOR X] 

(QUOTE O) 
(EQUAL (CADDR SS2) (CAR X] 
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X:(#l 'A 'B 'C #1 $) Similar to the pattern above, except that -- specifies 

a search for any 6 followed by a C followed by the 

first element, so the translation is: 

[AND (EQ (CAOR X) (QUOTE A)) 

(SOME (CDDR X) (FUNCTION (LAMBDA ($$2 $$1) 
(AND (EQ SS2 (QUOTE B)) 

(EQ (CADR SSI) (QUOTE C)) 
(EQUAL (CADDR SSI) (CAR X] 

This concludes the description of the pattern match compiler. 
23.11 The Record Package ^^ 

The advantages of "data-less** or data-structure^indepehdent programming have 
long been known: more readable code, fewer bugs, the ability to change the data 
structure without having to make major modifications to the program, etc. The 
record package in CLISP both encourages and facilitates this good programming 
practice by providing a uniform syntax for accessing and storing data into many 
different typos of data structures, e.g. those employing arrays, list 
structures, atom property lists, hash links, etc., or any combination thereof, 
as well as removing from the user the task of writing the various access and 
storage routines themselves. The user declares (once) the data structure(s) 
used by his programs, and thereafter indicates the manipulations of the data in 
a data-structure-independent manner. The record package automatically computes 
from the declaration(s) the corresponding INTERLISP expressions necessary to 
accomplish the indicated access/storage operations. The user can change his 
data structure simply by changing the corresponding declaration(s) , and his 
program automatically (re)adjusts itself to the new conventions. 



The record package was written by L. N. Nasinter. 
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The user informs the record package about the format of his data structure by 
making a record declaration. A record declaration defines a record , i.e. a 
data structure. (Note that the record itself is an abstraction that exists 
only in the user's head.) The record declaration is essentially a template 
which describes the record, associating names with its various parts or fields. 
For example, the record declaration (RECORD MSG (ID (FROM TO) . TEXT)) 
describes a data structure called MSG, which contains four fields: 10, FROM, 
TO, and TEXT. The user can then reference these fields by name, either to 
retrieve their contents, or to store new data into them, by using the : 
operator followed by the field name. For example, for the above record 
declaration, X:FROM would be equivalent (and translate) to (CAADR X), and 
Y:TO-Z to (RPLACA (COADR Y) Z) The fields of a record can be further broken 
down into subfields by additional declarations within the record, e.g. 
(RECORD MSG (ID (FROM TO) . TEXT) (RECORD TEXT (HEADER TXT))) would permit the 
user to refer to TEXT, or to its subfields HEADER and TXT. 

Note that what the record declaration is really doing is specifying the 
data-paths of the structure, and thereby specifying how the corresponding 
access/storage operations are to be carried out. For example, 
(RECORD MSG (ID (FROM TO) . TEXT) (RECORD TEXT (HEADER TXT))) says the HEADER 
of a MSG is to bo found as the first element of its TEXT, which is the second 
tail of the MSG itself. Hence, X:HEADER**str ing is achieved by performing 
(RPLACA (CDDR X) string). 

Note also that when the user writes X:HEADER, he is implicitly saying the X is 
an instance of the record MSG, or at least is to be treated as such for this 
particular operation. In other words, the interpretation of XrFORM never 
depends on the value of X, The record package (currently) does not provide any 



or /RPLACA or FRPLACA, depending on the CLISP declaration in effect. 
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facility which uses run-time checks to dotormine data paths, nor is there any 
error checking other than that provided by INTERLISP itself. For example, if X 
happened to be an array, X:HEADER would still compute (CAADR X). 

RECORD (used to specify elements and tails of a list structure) is just one of 
several record-types currently implemented. For example, the user can specify 
'optional' fields, i.e. property list format, by using the record type 
PROPRECORD, or fields to be associated with parts of the data structure via 
hash links, by using the record-type HASHRECORO, or even specify the access 
definitions in the record declaration himself, by using the record-type 
ACCESSFN. These are described in detail below. 

The record package also provides a facility for creating new data structures 
using a record declaration as a guide or template. Initial values for the 
various fields can be specified in the CREATE expression, or defaulted to 
values specified in the record declaration itself. Alternatively, CREATE can 
be instructed to use an existing datum as a model, i.e. to obtain the field 
values for the new datum from the corresponding fields of the existing datum, 
or even to actually use (cannibalize) the structure of the existing datum 
itself. 

As with all DWIN/CLISP facilities, the record package contains many 
do-what-I-mcan features, spelling correction on field names, record types, etc. 
In addition, the record package includes a RECORDS prettydef macro for dumping 
record declarations, as well as the appropriate modifications to the file 
package (Section 14), so that files? and cleanup will inform the user about 
records that need to be dumped. 



However, it is possible to make the interpretation of X:HEADER differ from 
that of Y:HEADER (regardless of the values of X and Y), by using local 
record declarations, as described on page 23.35. Note that this 
distinction depends on a translation-time check, not run-time. 
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Record Declarations 



A record declaration is an expression of the form 

(record-type record-name fields . (defaults and/or subfields}) 
This expression is evaluated to effect the corresponding declaration .^^ 

^' record-type specifies the "type* of data being described by the record 
declaration* and thereby implicitly specifies the data paths, i.e. how the 
corresponding access/storage operations are performed. record-type 
currently is either RECORD. TYPERECORD, ARRAYRECORD. ATOMRECORD. PROPRECORD. 
HASHRECORD» or ACCESSFN.''^ RECORD and TYPERECORD are used to describe list 
structures, ARRAYRECORD to describe arrays, ATOMRECORD to describe (the 
property list of) atoms, and PROPRECORD to describe lists that use property 
list format. HASHRECORD can be used with any type of data: since it simply 
specifies the data path to be a hash-link. ACCESSFN is also type-less; the 
user specifies the data-path(s) in the record declaration itself, as 
described below. 

Z. record-name is a literal atom used to identify the record declaration for 
dumping to files via the RECORDS prettydof macro, and for creating instances 
of the record via CREATE. For most top-level declarations, record-name is 
optional, e.g. (RECORD (ID (FROM TO) . TEXT)) is perfectly acceptable .^^ 
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Local record declarations are performed by including an expression of this 
form in the CLISP declaration for that function (page 23.35), rather than 
evaluating the expression itself. 

When user-defined data types are introduced to INTERLISP, a corresponding 
record- type will be added to the record package. 

record-name is omitted, it simply means that the user cannot specify the 
record by name, e.g. when calling CREATE, or when using the RECORDS 
prettydef command. 
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For TYPERECORD, record-name is obligatory and is used as an indicator in CAR 
of the datum to signify what "type" of record it is. CREATE will insert an 
extra field containing record-name at the beginning of the structure, and 
the translation of the access and storage functions will take this extra 

77 

field into account. 

For subfield declarations, record-name is also obligatory, and specifies the 
parent field that is being elaborated, as described below. 

3. fields describes the structure of the record. Its exact interpretation 
varies with the record-type i 

For RECORD, fields is a list whose non-NIL literal atoms are taken as 
field-names to be associated with the corresponding elements and 
tails of a list structure. NIL can bo used as a place marker to fill 
an unnamed field, e.g. (A NIL B) describes a three element list, with 
B corresponding to the third element. 

For TYPERECORD, fields has the same meaning as for RECORD. However, 
since CAR of the datura contains an indicator signifying its "type," 
the translation of the access/storage functions differ from those of 
RECORD. For example, for (TYPERECORD MSG (ID (FROM TO) . TEXT)). 
X:FROM translates as (CAADDR X), not (CAADR X). 

For ATOMRECORO, fields is a list of property names, e.g. 
(ATOMRECORO (EXPR CODE MACRO BLKLIBRARYDEF) ) . Accessing will be 
performed with getp , storing with put . 



Note: this type-field is not used by the record package. It is provided 
for the user's own applications. 
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For PROPRECORO, fields is also a list of property names. Accessing 
is pGrformed with get, storing with putl . For example, 
(RECORD ENTRY (INPUT VALUE 10 . PROPS) (PROPRECORO PROPS (HISTORY 
LISPXPRINT SIDE GROUP ERROR))) could be used to describe an entry on 
the history list (see Section ZZ)/^ 

For HASHRECORD (or HASHLINK), fields is usually just field-name , i.e. 
an atom, and is the name by which the corresponding hash-value is 
referred to. For example, for (RECORD (A B . C) (HASHRECORD B FOO)). 
X:FOO translates as (GETHASH (CADR X)). If field-name is a list, it 
is interpreted as (field-name arrayname arraysize). In this case, 
arrayname indicates the hash-array to be used. For example, 
(HASHRECORD (CLISP CLISPARRAY)) would permit the user to obtain the 
CLISP translation of X by simply writing X:CLISP. arraysize is used 
for initializing the hash array: if arrayname has not been 
initialized at the time of the declaration, it will be set to 
(HARRAY (OR arraysize 100)). 

For ARRAYRECORD, fields is a list of field-names that are associated 
with the corresponding elements of the array. NIL can be used as a 
place marker for an unnamed field (element). Positive integers can be 
used as abbreviation for the corresponding number of NILs. For 
example, (ARRAYRECORD (ORG DEST NIL ID 3 TEXT)) describes an eight 



A new function (part of the record package), similar to put , which takes a 
list as its first argument, searches the list looking for an occurrence of 
the given property name (its second argument). If found, it replaces the 
next element with the now property value (its third argument), otherwise 
adds the property name and property value to the list. 



Note that (ATOMRECORO (FOO FIE))) is equivalent to (RECORD (VALUE . PROPS) 
(PROPRECORO PROPS (FOO FIE))), the difference being in the translations. 
In the first case, X:FIE translates as (GETP X (QUOTE FIE)),, in the second 
case, as (GET (COR X) (QUOTE FIE)). Note also that in the first case, if X 
is not a literal atom, INTERLISP (i.e. getp ) will generate an error. 
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olcmGnt array, with ORG corresponding to the first element, 10 to 
the fourth, and TEXT to the eighth. 

For ACCESSFN (or ACCESSFNS), fields is a list of the form 

(field-name accessdef inition setdefinition), or a list of elements of 

this form, accessdef inition is a function of one argument, the datum, 

and will be used for accessing, setdefinition is a function of two 

SO 

arguments, the datum and the new value, and is used for storing. 
For example, (HASHRECORD FOO) and (ACCESSFN (FOO GETHASH PUTHASH)) 
are equivalent: in both cases, X:FOO translates as (GETHASH FOO). 
Similarly, (ACCESSFN (DEF GETO PUTO)) would permit defining functions 
by writing fn:DEF«-def inition. 

4. {defaults and/or subfields} is optional. It may contain expressions of the 
form: 

(1) field-name form - specifies the default value for f ield-name . 
Used by CREATE. 

(2) DEFAULT «- form - specifies default value for every field not 
given a specific default via (1). 

(3) a subfield declaration - i.e. a record declaration of any of the 
above types. For subfield declarations, record-name is obligatory. 
Instead of identifying! the declaration as with the case of top level 
declarations, record-name identifies the parent field or record that 
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Currently, an error is generated if CREATE is called with a record' 
declaration containing an ACCESSFNS record-type. 

[ACCESSFN (DEF GETD (LAMBDA (FN DEF) (DEFINE (LIST (LIST FN DEF] would be 
preferable to using putd . 
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is being described by the subfield declaration. It must be either the 
record-name of the immediately superior declaration, or one of its 
field-names (or else an error is generated). 

Subfields can be nested to an arbitrary depth. 

Note that in some cases, it makes sense for a given field to have 
more than one subfield declaration. For example, in 
(RECORD (A . B) (PROPRECORO B (FOO FIE FUM)) (HASHRECORD B C)), B is 
elaborated by both a PROPRECORO and HASHRECORD. Similarly, 
(RECORD (A B) (RECORD A (C D)) (RECORD A (FOO FIE))) is also 
acceptable, and essentially "overlays" (FOO FIE) and (CO), i.e. 
X:FOO and X:C would be equivalent. In such cases, the first subfield 
declaration is the one used by CREATE, e.g. 

(RECORD X (A B) (RECORD A (C D)) (RECORD A (FOO FIE FUM)) ) will 
cause (CREATE X) to construct ((NIL NIL) NIL), not 
((NIL NIL NIL) NIL), as would be the case if the subfield declaration 
(RECORD A (C D)) were removed. 

CREATE 

Record operations can be applied to arbitrary structures, i.e. structures 
created directly by user programs can be manipulated in a data-independent 
manner using record declarations. However, to be completely data-independent, 
now data should be created using the same declarations that define its data 
paths. This can be done by means of an expression of the form 
(CREATE record-name . {assignments} ) (assignments) is optional and may 



CREATE is not defined as a function. Instead, DWIN calls the appropriate 
function in the record package giving it the entire CREATE expression as an 
argument. The translation of the CREATE expression, i.e. the INTERLISP 
form which is evaluated to construct the datum, is then stored elsewhere, 
as with iterative statements and pattern matches. 
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contain expressions of the following form: 



(1) field-name «- form 



specifies initial value for field-name . 



(2) USING form 



specifies that for all fields not given a 



value by (1), the value of the corresponding 



field in form is to be used. 



(3) COPYING form 



like USING except the corresponding values 



are copied ( copy ) . 



(4) REUSING form 



like USING, except that wherever possible. 



the corresponding structure in form is used 



(similar to operation of subpair and sublis ) . 



For example, following (RECORD FOO (ABC)), 

(CREATE FOO A«-T USING X) translates as (LIST T (CADR X) (CADOR X)), 

(CREATE FOO A-T COPYING X)) as (LIST T (COPY (CADR X)) (COPY (CADDR X))), and 

(CREATE FOO A-T REUSING X) as (CONS T (CDR X)). 

A CREATE expression translates into an appropriate INTERLISP form using cons , 
list , put , putl , puthash , seta , etc., that creates the new datum with the 
various fields initialized to the appropriate values. If values are neither 
explicitly specified, nor implicitly specified via USING or COPYING, the 



23.56 



DEFAULT value in the declaration is used, if any, otherwise NIL. 



Implementation 

Record operations are implemented by replacing expressions of the form X:FOO by 
(FETCH FOO OF X). and X:FOO^Y by (REPLACE FOO OF X WITH Y),^^ and then storing 
the translation elsewhere, usually in a hash array, as described on page 23.30. 
Translations of CREATE expressions are also stored elswhere. 

The translation of each record operation is computed using information 
retrieved from the property list of the field name, under the property 
CLISPRECORDFIELO. Thus, (global) field names must be unique, i.e. cannot be 
the same as the name of any other field in any other record. Records can also 
bo declared local to a particular function by using a CLISP declaration, as 
described on page 23.35. Local record declarations override global ones, and a 
local record can have a field name the same as that of a local record of 
another function, or the same as a field name of a global record. 

For both global and local records, the translation is computed using all CLISP 
declarations in effect as described on page 23.33, e.g. if the declaration 
UNDOABLE in in effect, /RPLACA, /RPLACD, /PUTHASH, etc. will be used. 



For RECORD and TYPERECORD declarations with non-NIL defaults, all elements 
and named tails will be initialized; unnamed tails will not be initialized. 
For example, (RECORD FOO (A NIL B) OEFAULT*-T) will cause (CREATE FOO) to 
construct (T T T) not (T T T . T). Of course, 

(RECORD FOO (A B . C) DEFAULT*-T) will cause (CREATE FOO) to construct 
(T T . T) as expected. 



For PROPRFCORD, initialization is only performed where necessary. For 
example, (RECORD FOO (A B) (PROPRECORD (C D E))) would cause (CREATE FOO) 
to construct (NIL NIL), not (NIL (C NIL D NIL E NIL)). 

(RECORD FOO (A B) (PROPRECORD (C 0 E) DEFAULT«-T)) however, will construct 
(NIL (C T D T E T)). 

CLISP also recognizes expressions input in this form. 
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When the user redcclares a global recordt the translations of all expressions 

SO 

involving that record are automatically deleted, and thus will be recomputed 
using the new information. If the user changes a local record declaration, or 
changes some other CUSP declaration, e.g. STANDARD to FAST, and wishes the new 
information to affect record expressions already translated, he must make sure 
the corresponding translations are removed, usually either by CLISPIFYING or 
changing the expression by editing it. 



Z3.12 CLISPIFY 



Clispify converts INTERLISP expressions to CLISP. Note that the expression 
given to clispify need not have originally been input as CLISP, i.e., clispify 
can be used on functions that were written before CLISP was even implemented. 
Clispif y is cognizant of declaration rules as well as all of the precedence 
rules. For example, clispify will convert (IPLUS A (ITIMES B C)) into A+B*C, 
but (ITIMES A (IPLUS B C)) into A*(B+C).** Clispify converts calls to the six 
basic mapping functions, MAP, MAPC, MAPCAR, MAPLIST, MAPCONC. and MAPCON. into 
equivalent iterative statements. It also converts certain easily recognizable 
internal PROG loops to the corresponding i.s. For example. 



from clisparra y. If the user is not using this method for storing 
translations, i.e. is instead using the CLISP%_ method (page 23.31), those 
expressions already translated will remain as they are. (There is no 
practical way to locate them.) 



clis pi f y is table driven exactly the same as CLISP, so that if the user 
changes any precedence, or defines new operators, clispify "automatically" 
knows about it. 



^^\.^Plfy also knows how to handle expressions consisting of a mixture of 
INTERLISP and CLISP, e.g. (IPLUS A B«C) is converted to A+B*C, but 
(ITIMES A B+C) to (A*(B+C)). clispify handles such cases by first 
dwimify ing the expression. 
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... label (COND (pred ... forms ... (GO label))) ... 

becomes 

... label (WHILE pred DO . . . forms ...) ... 



CI ispify is not destructive to the original INTERLISP expression, i.e. clispify 
produces a new expression without changing the original. Clispify will not 
convert expressions appearing as arguments to NLAMBDA functions. 

The value of various global parameters affect the operation of clispify : 

cl : f Ig 

The user can disable the : transformation by setting the variable cl;f Ig to 
NIL. This will cause clispify not to transform expressions such as (CAOR X) to 
X:2. Note that clispify does not convert to : notation when the argument is 
not atomic or a simple list (a function name and one atomic argument), 
regardless of the setting of this flag. The initial value of cl;f Ig is T. 

clrcmparsf Ig 

Clispify will remove parentheses in certain cases from simple forms, where 
•simple' means a function name and one or two atomic arguments. For example, 
(COND ((ATOM X) --)) will CLISPIFY to (IF ATOM X THEN --). However, if 
clremparsflg is set to NIL, clispify will produce (IF (ATOM X) THEN --). Note 
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clispify can convert all iterative statements input in CLISP back to CLI5P, 
regardless of how complicated the translation was, because the original 
CLISP is saved. 

The now expression may however contain some 'pieces' of the original, since 
clispify attempts to minimize the number of CONSes by not copying structure 
whenever possible. 



Except for those functions for which clispify contains built in information 
about how they process their arguments, e.g. prog , selectq , function . 
prog n. ersetq , nlsetq . resetvar , resetform . etc. 
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that regardless of the setting of this flag, the expression can be input in 
either form. The initial value of clremparsflg is T. 



clispif ypac kf Ig 

clispifypackfl g affects the treatment of infix operators with atomic operands. 
If clispifypackf Ig is T, clispify will pack these into single atoms, e.g., 
(IPLUS A (ITIMES B O) becomes A+B'C. If clispifypackf Ig is NIL, no packing is 
done, e.g., the above becomes A_+_B_*__C. The initial value of clispifypackf Ig 
is T. 

f unnyatomlst 

Suppose the user has variables named A, B, and A*B. If clispify were to 
convert (ITIMES A B) to A*B, A*B would not translate back correctly to 
(ITIMES A B), since it would be the name of a variable, and therefore would not 
cause an error. The user can prevent this from happening by adding A*B to the 
list funnyatoml st . Then, (ITIMES A B) would clispify to A__*_B. 

Note that A*B's appearance on funnyatomlst would not enable DWIM/CLISP to 
decode A*B+C as (IPLUS A*B.C); funnyatomlst is used only by clispify . Thus, if 
an identifier contains a CUSP character, it should always be separated (with 
spaces) from other operators. For example, if X* is a variable, the user 
should write (SETQ X* form) in CLISP as X* «-form, not X*«-form. However, in 
general, it is best to avoid use of identifiers containing CLISP character 
operator s as much as possible , 

cl is pif yprct tyf Ig 

If T, causes p rettyprint to clispify all expressions before printing them (but 
not to redefine any functions), c 1 ispif ypret tyf Ig is temporarily reset to T, 
using rcsetvar , when makefile is called with the option CLISPIFY, or when the 
file in question has property FILETYPE with value CLISP on its property list. 
clispifyprettyf Ig is initially NIL. 
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In addition to the above controls, disabling a CLISP operator (see cldisable , 
page 23.74) will also disable the corresponding CLISPIFV transformation. 
Thus» if is "turned off, A»-B will not transform to (SETQ A B), nor vice 
versa. 

23>13 Dwimify 

Pwimify is effectively a preprocessor for CLISP. Dwimify operates by scanning 
an expression as though it were being interpreted* and for each form that would 

OP 

generate an error, calling DWIM to 'fix* it. Thus the user will see the same 
messages, and be asked for approval in the same situations, as he would if the 
expression were actually run. If DWIN is unable to make a correction, no 
message is printed, the form is left as it was, and the analysis proceeds. 

Dwimify knows exactly how the interpreter works. It knows the syntax of progs , 
solcctq s, lambda expressions, setqs , et al. It knows that the argument of 
n lambdas are not evaluated. It also knows how variables are bound. In the 
course of its analysis of a particular expression, dwimify builds a list of the 
bound variables from the LAMBDA expressions and PROGs that it encounters. It 
uses this list for spelling corrections. Dwimify also knows not to try to 
'correct' variables that are on this list since they would be bound if the 
expression were actually being run. However, note that dwimify cannot, a 
priori, know about variables that are used freely but would be bound in a 
higher function if the expression were evaluated in its normal context. 
Therefore, dwimify will try to 'correct' these variables. Similarly, dwimify 



Thus dwim ify performs all DWIN transformations, not Just CLISP 
transformations, i.e., it does spelling correction, fixes 8-9 errors, 
handles F/L, etc. 
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will attempt to correct forms for which car is undefined, even when the form is 
not in error from the user's standpoint, but the corresponding function has 
simply not yet been defined. 

In most cases, an attempt to transform a form that is already as the user 
intended will have no effect (because there will be nothing to which that form 
could reasonably be transformed). However, in order to avoid needless calls to 
DWIN or to avoid possible confusion, the user can inform dwimify not to attempt 
corrections or transformations on certain functions or variables by adding 
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them to the list nof ixfnslst or nofixvarslst respectively. 

Dwimif y and dwimifyfns (used to dwimify several functions) maintain two 
internal lists of those functions and variables for which corrections were 
unsuccessfully attempted. These lists are initialized to nof Ixfnslst and 
nofixv arslst . Once an attempt is made to fix a particular function or 
variable, and the attempt fails, the function or variable is added to the 
corresponding list, so that on subsequent occurrences (within this call to 
dwimify or dwimifyfns ) , no attempt at correction is made. For example, if FOO 
calls FIE several times, and FIE is undefined at the time FOO is dwimified, 
dw imify will not bother with FIE after the first occurrence. In other words, 
once dwi mify "notices" a function or variable, it no longer attempts to correct 
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it."^ Moreover, once dwimify "notices" such functions or variables, it 
subsequently treats them the same as though they were actually defined or set. 

Note that these internal lists are local to each call to dwimify and 
dwimifyf ns , so that if a function containing FOOO, a misspelled call to FOO, is 



Nlotfi that the user could achieve the same effect by simply setting the 
corresponding variables, and giving the functions dummy definitions. 

Dwimify and dwimifyf ns also "notice" free variables that are set in the 
expression being processed. 
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(Iw imif ied before FOO is defined or mentioned, if the function is dwimified 
again after FOO has been defined, the correction will be made. 

Note that the user can undo selected transformations performed by dwimify , as 
described in section 22. 

Compiling CLISP 

Since the compiler does not know about CLISP, in order to compile functions 
containing CLISP constructs, the definitions must first be dwimified . The user 
can automate this process in several ways: 

1) If the variable dwimifycompf Ig is T, the compiler will always dwimlfy 
expressions before compiling them, dwimifycompf Ig is initially NIL. 

2) If a file has the property FILETYPE with value CLISP on its property list, 
tcom pl , bcomp l . recompile , and brecompile will operate as though dwimifycompf Ig 
is T and dwimify all expressions before compiling. 

3) If the function definition has a CLISP declaration (see page 23.33), 
including a null declaration, i.e.. Just (CLISP:), the definition will be 
automatically dwimified before compiling. 

Note: tcompl , hcompl , recompile , and brecompile all scan the entire file before 
doing any compiling, and take note of the names of all functions that are 
defined in the file as well as the names of all variables that are set by 
adding them to nof ixfnslst and nof ixvarslst , respectively. Thus, if a function 



If the value of property FILETYPE is CLISP, makefile would have 
automatically clispified all functions before prettyprinting, as described 
in Section 14. 
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is not currently defined, but is defined in the file being compiled, when 
dwimify is called before compiling, it will not attempt to correct the function 
when it appears as car of a form. 



Note: cotnpilcuscrfn (Section 18) is defined to call dwimify on iterative 
statements, as well as IF-THEN statements. Thus, if the only CLISP constructs 
in a function appear inside of iterative statements or IF statements, the 
function does not have to be dwimified before compiling. 

23.14 Operation 

CLISP is a part of the basic INTERLISP system. Without any special 
preparations, the user can include CLISP constructs in programs, or type them 
in directly for evaluation (in eval or apply format), and when the "error" 
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occurrs, and DWIM is called, it will destructively transform the CLISP to the 

equivalent INTERLISP expression and evaluate the INTERLISP expression. User 

07 

approval is not requested, and no message is printed. 

However, if a CLISP construct contains an error, an appropriate diagnostic is 
generated, and the form is left unchanged. For example, if the user writes 
(LIST X+Y*), the error diagnostic MISSING OPERAND AT X+V* IN (LIST X+Y* ) would 
be generated. Similarly, if the user writes (LAST-i-EL X), CLISP knows that 
((IPLUS LAST EL) X) is not a valid INTERLISP expression, so the error 
diagnostic MISSING OPERATOR IN (LAST-t-EL X) is generated. (For example, the 
user might have meant to say ( LAST-fEL'X) . ) Note that if LAST-i-EL were the name 
of a defined function, CLISP would never see this form. 



CLISP transformations, like all DWIM corrections, are undoable. 

This entire discussion also applies to CLISP transformation initiated by 
calls to DWIM from dwimify . 
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Since the bad CLISP transformation might not be CLISP at all, for example, it 
might be a misspelling of a user function or variable, DWIN holds all CLISP 
error messages until after trying other corrections. If one of these succeeds, 
the CLISP message is discarded. Otherwise, if all fail, the message is printed 

no 

(but no change is made). For example, suppose the user types (R/PLACA X Y). 
CLISP generates a diagnostic, since ((IQUOTIENT R PLACA) X Y) is obviously not 
right. However, since R/PLACA spelling corrects to /RPLACA, this diagnostic is 
never printed. 

If a CLISP infix construct is well formed from a syntactic standpoint, but one 
or both of its operands are atomic and not bound, it is possible that either 
the operand is misspelled, e.g., the user wrote X+YY for X+Y, or that a CLISP 
transformation operation was not intended at all, but that the entire 
expression is a misspelling. For example, if the user has a variable named 
LAST-EL, and writes (LIST LAST-ELL). Therefore, CLISP computes, but does not 
actually perform, the indicated infix transformation. DWIN then continues, and 
if it is able to make another correction, does so, and ignores the CLISP 
interpretation. For example, with LAST-ELL, the transformation 
LAST-ELL -> LAST-EL would be found. 

If no other transformation is found, and DWIM is about to interpret a construct 
as CLISP for which one of the operands is not bound, DWIN will ask the user 
whether CLISP was intended, in this case by printing 



^ Except that CLISP error messages are not printed on type-in. For example, 
typing X+*Y will just produce a U.B.A. X+*Y message. 
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For the purpose of dwimifying , , 'not bound' means no top lovol value, not 
on list of bound variables built up by dwlmify during its analysis of the 
expression, and not on nof ixvarslst , i.e., not previously seen. 
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LAST-ELL TREAT AS CLISP 7 



The same sort of procedure is followed with 8 and 9 errors. For example, 
suppose the user writes F008*X whore F008 is not bound. The CLISP 
transformation is noted, and DWIK proceeds. It next asks the user to approve 
FOOO*X -> FOO ( *X. (For example, this would make sense if the user has (or 
plans to define) a function named *X.) If ho refuses, the user is asked 
whether F008*X is to be treated as CLISP. Similarly, if F008 were the name of 
a variable, and the user writes F0008*X, he will first be asked to approve 
F0008«X -> FOOO ( XX. and if he refuses, then be offered the F0008 -> F008 
correction. 

CLISP also contains provision for correcting misspellings of infix operators 
(other than single characters), IF words, and i.s. operators. This is 
implemented in such a way that the user who does not misspell them is not 
penalized. For example, if the user writes IF N=0 THEN 1 ELSSE N*(FACT N-1) 
CLISP does not operate by checking each word to see if it is a misspelling of 
IF, THEN, ELSE, or ELSEIF, since this would seriously degrade CLISP's 
performance on all IF statements. Instead, CLISP assumes that all of the IF 
words are spelled correctly, and transforms the expression to 
(COND ((ZEROP N) 1 ELSSE N*(FACT N-1))). Later, after DWIM cannot find any 
other interpretation for ELSSE, and using the fact that this atom originally 
appeared in an IF statement, DWIN attempts spelling correction, using 



If more than one infix operator was involved in the CLISP construct, e.g., 
X+Y-^Z, or ihe operation was an assignment to a variable already noticed, or 
troa ta.sclispfig is T (initially NIL), the user will simply be informed of 
the correction. Otherwise, even if DWIM was enabled in TRUSTING mode, the 
user will be asked to approve the correction. 



The 8-9 transformation is tried before spelling correction since it is 

empirically more likely that an unbound atom or undefined function 

containing an 8 or a 9 is a parenthesis error, rather than a spelling 
error . 
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(IF THEN ELSE ELSEIF) for a spelling list. When this is successful, DWIM 
'fails' all the way back to the original IF statement, changes ELSSE to ELSE, 
and starts over. Misspellings of AND, OR, LT, GT, etc. are handled similarly. 

CLISP also contains many Do-What-I-Nean features besides spelling corrections. 
For example, the form (LIST +X Y) would generate a MISSING OPERATOR error. 
However, (LIST -X Y) makes sense, if the minus is unary, so DWIN offers this 
interpretation to the user. Another common error, especially for new users, is 
to write (LIST X*FOO(Y)) or (LIST X«FOO Y), where FOO is the name of a 
function, instead of (LIST X*(FOO Y)). Therefore, whenever an operand that is 
not bound is also the name of a function (or corrects to one), the above 
interpretations are offered. 



23.15 CLISP Interaction with User 

Syntactically and semantically well formed CLISP transformations are always 
performed without informing the user. Other CLISP transformations described in 
the previous section, e.g. misspellings of operands, infix operators, 
parentheses errors, unary minus - binary minus errors, all follow the same 
protocol as other DWIN transformations (Section 17). That is, if DWIN has been 
enabled in TRUSTING mode, or the transformation is in an expression typed in by 
the user for immediate execution, user approval is not requested, but the user 
is informed. However, if the transformation involves a user program, and 
DWIN was enabled in CAUTIOUS mode, the user will be asked to approve. If he 
says NO. the transformation is not performed. Thus, in the previous section. 



However, in certain situations, DWIN will ask for approval even if DWIM is 
enabled in TRUSTING mode. For example, the user will always be asked to 
approve a spelling correction that might also be interpreted as a CLISP 
transformation, as in LAST-ELL -> LAST-EL. 
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phrases such as "one of these (transformations) succeeds" and "the 
transformation LAST-ELL -> LAST-EL would be found" etc., all mean if the user 
is in CAUTIOUS mode and the error is in a program, the corresponding 
transformation will be performed only if the user approves (or defaults by not 
responding). If the user says NO, the procedure followed is the same as though 
the transformation had not been found. For example, if A*B appears in the 
function FOO, and B is not bound (and no other transformations are found) the 
user would be asked 

A«B [IN FOOl TREAT AS CLISP ? 
If the user approved, A^B would be transformed to (ITINES A B), which would 
then cause a U.B.A. B error in the event that the program was being run 
(remcmbor the entire discussion also applies to DWINIFYing). If the user said 
NO, A*B would be left alone. 



23.16 CLISP Internal Convention s 

Note: the reader can skip this section and proceed to "Function and Variables" 
(page 23.71), unless he wants to add now operators, or modify the action of 
existing ones (other than by making declarations). 

CLISP is almost entirely table driven by property lists for the corresponding 
infix or prefix operators. Thus it is relatively easy to add new infix or 
prefix operators or change old ones, simply by adding or changing selected 
property values. 
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The waiting time on such interactions is three times as long as for simple 
corrections, i.e., 3* dwimwait . 

There is some built in information for handling minus, :, ', <, >, and 
i.e., the user could not himself add such 'special' operators, although he 
can disable them. 
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CLISPTYPE The property value of the property CLISPTYPE is the 

precedence number of the operator higher values 
have higher precedence^ i.e. are tighter. Note that 
the actual value is unimportant, only the value 
relative to other operators. For example, CLISPTYPE 
for : , and * are 14, 6, and 4 respectively. 
Operators with the same precedence group left to right, 
e.g., / also has precedence 4, so A/B*C is (A/B)*C. 

An operator can have a different left and right 
precedence by making the value of CLISPTYPE be a dotted 
pair of two numbers, e.g., CLISPTYPE of is (8 . -12). 
In this case, car is the left precedence, and cdr the 
right, i.e., car is used when comparing with operators 
on the left , and cdr with operators on the right. For 
example, A'B^-C+D is parsed as A*(B*-(C+0)) because the 
left precedence of *• is 8, which is higher than that of 
*, which is 4. The right precedence of ♦- is -12, which 
is lower than that of *, which is 2. 

If the CLISPTYPE property for any infix operator is 
removed, the corresponding CLISP transformation is 
disabled, as well as the inverse CLISPIFY 
transformation. 

UNARYOP The value of property UNARYOP must be T for unary 

operators. The operand is always on the right, i.e., 
unary operators are always prefix operators. 



Unless otherwise specified, the property is stored on the property list of 
the operator. 
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The value of property BROADSCOPE Is T if the operator 
has lower precedence than INTERLISP forms, e.g., LT, 
EQUAL, AND, etc. For example, (FOO X AND Y) parses as 
((FOO X) AND Y). If the BROADSCOPE property were 
removed from the property list of AND, (FOO X AND Y) 
would parse as (FOO (X AND Y)). 

The value of the property LISPFN is the name of the 
function to which the infix operator translates. For 
example, the value of LISPFN for t is EXPT, for ' 
QUOTE, etc. If the value of the property LISPFN is 
NIL, the infix operator itself is also the function 
e.g., AND, OR, EQUAL. 

If TOO has a SETFN property FIE, then (FOO --)*-X 
translates to (FIE -- X). For example, if the user 
makes ELT be an infix operator, e.g. #, by putting 
appropriate CLISPTYPE and LISPFN properties on the 
property list of # then he can also make # followed by 
- translate to SETA, e.g. X#N-Y to (SETA X N Y), by 
putting SETA on the property list of ELT under the 
property SETFN. Putting (ELT) (i.e. list[ELT])) on the 
property list of SETA under property SETFN will enable 
SETA forms to CLISPIFY back to ELT 's. 

The value of this property is the CLISP infix to be 
used in CLISPIFYing. This property is stored on the 
property list of the corresponding INTERLISP function, 
e.g., the value of property CLISPINFIX for EXPT is r, 
for QUOTE is • etc. 
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Global declarations operate by changing the corresponding LISPFN and CLISPINFIX 

is a list of single character operators that can appear 
in the interior of an atom. Currently these are: +, 
*, /. t, a, <, and >. 

is a bit table of the characters on clispchars used for 
calls to strposl (see Section 10). clispcharray is 
initialized by performing 

(SETO CLISPCHARRAY (MAKEBITTABLE CLISPCHARS)). 

is a list of infix operators used for spelling 
correction. 

As an example, suppose the user wants to make i be an infix character operator 
moaning OR. Ho performs: 

-(PUT (QUOTE I) (QUOTE CLISPTYPE) (GETP (QUOTE OR) (QUOTE CLISPTYPE))) 
-PUT(| LISPFN OR) 
-PUT(| BROADSCOPE T) 
-PUT(OR CLISPINFIX | ) 

-SETQ(CLISPCHARS (CONS (QUOTE |) CLISPCHARS)) 
-SETO( CLISPCHARRAY (MAKEBITTABLE CLISPCHARS)) 



properties , 



clispchars 



clispcharray 



clispinf ixes 



23.17 CLISP Functions and Variables 

clispflg if set to NIL, disables all CLISP infix or prefix 

transformations (but does not affect IF/THEN/ELSE 
statements, or iterative statements). 

If clispflg =TYPE~IN, CLISP transformations are 
performed only on expressions that are typed in for 
evaluation, i.e. not on user programs. 
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If clispflg sT, CLI5P transformations are performed on 
all expressions. 

The initial value for clispf Ig is T. clispify ing 
anything will cause clispf Ig to be set to T. 



clisparray 



hash array used for storing translations, clisparray 
is checked by faulteval on erroneous forms before 
calling DWIN, and by the compiler. 



nof ixfnslst 



list of functions that dwimify will not try to correct 
See page 23.62. 



nof ixvarslst 



list of variables that dwimify will not try to correct 
See page 23.62. 



nospellf Ig 



If nospellflg is T, dwimify will not perform any 
spelling corrections. The initial value of nospellflg 
is NIL. 



dwimify[x; 1 ] 



dwimifies x, i.e., performs all corrections and 
transformations that would be performed if x were run. 
If X is an atom and 1 is NIL, x is treated as the name 
of a function, and its entire definition is dwimified. 
Otherwise, if x is a list or 1 is not NIL, x is the 
expression to be dwimified. If 1 is not NIL, it is the 
edit push-down list leading to x, and is used for 
determining context, i.e., what bound variables would 
be in effect when x was evaluated, whether x is a form 
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or sequence of forms, e.g., a cond clause, etc. 



dwimifyfnsCfns] nlambda, nospread. Dwimifies each function on fns. If 

fns consists of only one element, the value of car[fns3 
is used, e.g., dwimifyfns[FOOFNS]. Every 30 seconds, 
dwimifyfns prints the name of the function it is 
processing, a la prettyprint . 

dwimifycoropf Ig if T, dwimify is called before compiling an expression. 

See page 23.63. 

clispdec[declst i puts into effect the declarations in declst . clispdec 

performs spelling corrections on words not recognized 
as declarations, clispdec is undoable. 

clispify[x:l] clispifies x. If x is an atom and 1 is NIL, x is 

treated as the name of a function, and its definition 
(or EXPR property) is clispified. After clispify has 
finished, x is redefined (using /PUTD) with its new 
CLISP definition. The value of clispify is x. If x is 
atomic and not the name of a function, spelling 
correction is attempted. If this falls, an error is 
generated. 

If X Is a list, or 1 is not NIL, x itself is the 
expression to be clispified. If 1 is not NIL, it is 
the edit push-down list leading to x and is used to 



If X is an iterative statement and 1 is NIL, dwimify will also print the 
translation, i.e. what is stored in the hash array. 
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dotcrmiino context as with dwimify , as well as to obtain 
the local declarations, if any. The value of clispify 
is the clispified version of x. 

See earlier section on CLISPIFY for more details. 

nlambda, nospread. Calls clispify on each member of 
fns under errorset protection. If fns consists of only 
one element » the value of car[fns] is used, e.g., 
clispifyfns[FOOFNS]. Every 30 seconds, clispifyfns 
prints the name of the function it is working, a la 
prettyprint . Value is list of functions clispify ed. 

disables oji, e.g. cldisable[-] makes - be Just another 
character. cldisable can be used on all CLISP 
operators, e.g. infix operators, prefix operators, 
iterative statement operators, etc. cldisable is 
undoable. 

affects handling of translations of IF|THEN|ELSE 
statements. If T, the translations are stored 
elsewhere, and the (modified) CLISP retained. If NIL, 
the corresponding COND expression, replaces the CLISP. 
clispiftranf Ig is initially NIL. See page 23.30. 

affects clispify 's handling of forms beginning with 
car, cdr;, ... cddddr . See page 23.59. 

affects clispify 's removal of parentheses from "small" 
forms. See page 23.59. 
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cllspifypacKflg if T, informs clispify to pack operator and atomic 

operands into single atoms; if NIL, no packing is done. 
See page 23.60. 

clispAfyprettyf Ig if T, causes prettyprint to CLISPIFV expressions before 

printing them, clispifyprettyf Ig is (temporarily) reset 
to T when makefile is called with the option CLISPIFY. 
clispifyprettyf Ig is "initially NIL. 

prettytranf Ig If T, causes prettyprint to print translations instead 

of CLISP expressions. This is useful for creating a 
file for compilation, or for exporting to a LISP system 
that does not have CLISP. prettytranf Ig is 
(temporarily) rdset to T when makefile is called with 
the option NOCLISP. If prettytranf Ig is CLISPX_, both 
the CLISP and translations are printed in appropriate 
; form* For mo,re details, see page 23.32. prettytranf Ig 
is initially NIL. 

PPT is both a function and an edit macro for prettyprinting 

translations. It performs a PP after first resetting 
prettytranf Ig to T» thereby causing any translations to 
be printed instead of the corresponding CLISP. 

CLISP: ; edit macro that obtains the translation of the correct 

expression, if any, from clisparray , and calls edite on 

. ■ . - . ■ it. 

funnyatomlst list of identifiers containing CLISP operators. Used 

by clispify to avoid accidentally constructing a user 
identifier, e.g., (HIMES A B) should not become A*B if 
A«B is the name of a PROG variable. See page 23.60. 
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edit macro. Replaces current expressiofi with 
CLISPIFYed current expression. Current expression can 
be an element or tail. 



DW edit macro. DWIMIFYs current expression* which can be 

an element (atom or list) or tail. 

Both CL and DW can be called when the current expression is either an element 
or a tail and will work properly. Both consult the declarations in the 
function being edited, if any, and both are undoable. 

lowercase[f Ig] If flg «T, lowercase makes the necessary internal 

modifications so that clispify will use lower case 
versions; of AND, OR, IF, THEN, ELSE, ELSEIF, and all 
i.s. operators. This produces more readable output. 
Note that the user can always type in either upper or 
lower case (or a combination), regardless of the action 
of lowercase . 

If flgsNIL, clispify will use uppercase versions of 
AND, OR, et al. The value of lowercase is its previous 
'setting*. Lowercase is undoable. 

lowercas e also sets model33f Ig to nullCflg], as well as 
performing raise[null[f Ig]]. modeI33f Ig affects the 
operation of the spelling corrector to the extent that 
it says something about the layout of the keyboard (see 
Section 17). raise[T] is the same as the TENIEX command 
RAISE, and informs TENEX to raise all lower case 
characters on input, i.e. convert them to uppercase. 
raise[ ] corresponds to NO RAISE. 
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Appendix 1 , 

Transor 

Introduction 

transor is a LISP-to-LISP translator intended to help the user vrho has a 
program coded in one dialect of llSP and wishes to carry it over to another. 
The user loads transor along with a file of trahsfornations. These 
transformations describe the differences between the two LISPs, expressed in 
terms of INTERLISP editor commands needed to convert th,e old to new» i.e. to 
edit forms written in the source dialect to make them suitable for the target 
dialect, transor then sweeps through the user's program and applies the edit 
transformations, producing an object file for the target system. In addition, 
transor produces a file of translation notes, which catalogs the major changes 
made in the code as well as the forms that require further attention by the 
user. Operationally, therefore, transor is a facility for conducting massive 
edits, and may be used for any purpose which that may suggest. 

Since the edit transformations are fundamental to this process, let us begin 
with a definition and some examples. A transformation is a list of edit 
commands associated with a literal atom, usually a function name. transor 
conducts a sweep through the user's code, until it finds a form whose car is a 
literal atom which has a transformation. The sweep then pauses to let the 
editor execute the list of commands before going on. For example, suppose the 
order of arguments for the function tconc must be reversed for the target 
system. The transformation for tconc would then be: ((SW 2 3)). When the 
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sweep encounters the foriD (TCONC X (FOO)), this transformation would bo 
retrieved and executed* converting the expression to (TCONC (FOO) X). Then the 
sweep would locate the next form, in this case (FOO), and any transformations 
for foo would be executed, etc. 

ffost instances of tconc would be successfully translated by this 
transformation. However, if there were no second argument to tconc , e.g. the 
form to be translated was (TCONC X), the command (SW Z 3) would cause an error, 
which transor would catch. The sweep would go on as before, but a note would 
appear in the translation listing stating that the transformation for this 
particular form failed to work. The user would then have to compare the form 
and the commands, to figure out what caused the problem. One might, however, 
anticipate this difficulty with a more sophisticated transformation: 
((IF (## 3) ((SW 2 3)) ((-2 NIL)))), which tests for a third element and does 
(SW 2 3) or (-2 NIL) as appropriate. It should be obvious that the translation 
process is no more sophisticated than the transformations used. 

This documentation is divided into two main parts. The first describes how to 
transor assuming that the user already has a complete set of 
transformations. The second documents transorset , an interactive routine for 
building up such sets, transorset contains commands for writing and editing 
transformations, saving one's work on a file, testing transformations by 
translating sample forms, etc. 

Two transformations files presently exist for translating programs into 
INTERLISP. <LISP>SDS940.XFORNS is for old BBN LISP (SDS 940) programs, and 
<LISP>LISP16.XF0RNS is for Stanford AI LISP 1.6 programs. A set for LISP 1.5 
is planned. 
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Using Transor 

The first and most exasperating problem in carrying a program from one 
implementation to another is simply to get it to read in. For example, SRI 
LISP uses / exactly as INTERLISP uses X, i.e. as an escape character. The 
function prescan exists to help with these problems: the user uses prescan to 
perform an initial scan to dispose of these difficulties, rather than 
attempting to transor the foreign sourcefiles directly. 

prescan copies a file, performing character-for-character substitutions. It is 
hand-coded and is much faster than either readc 's or text-editors. 

prescan[f ile;charlst] Makes a new version of file , performing 

substitutions according to charlst . Each element 
charlst must be a dot-pair of two character 
codes, (OLD . NEW). 

For example, SRI files are prescan 'ed with charlst ■ ((37 . 47) (47 . 37)), 
which exchanges slash (47) and percent-sign (37). 

The user should also make sure that the treatment of doublequotes by the source 
and target systems is similar. In INTERLISP, an unmatched double-quote (unless 
protected by the escape character) will cause the rest of the filQ to read in 
as a string. 

Finally, the lack of a STOP at the end of a file is harmless, since transor 
will suppress END OF FILE errors and exit normally. 

Translating 

transor is the top-level function of the translator itself, and takes one 
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argument, a file to be translated. The file is assumed to contain a sequence 
of forms, which are read in, translated, and output to a file called file.TRAN. 
The translation notes are meanwhile output to file.LSTRAN. Thus the usual 
sequence for bring a foreign file to INTERLISP is as follows: prescan the file; 
examine code and transformations, making changes to the transformations if 
needed; transor the file; and clean up remaining problems, guided by the notes. 
The user can now make a pretty file and proceed to exercise and check out his 
program. To export a file, it is usually best to transor it, then prescan it, 
and perform clean-up on the foreign system where the file can be loaded. 

Translates sourcefile . Prettyprints translation 
on file.TRAN: translation listing on file.LSTRAN. 

Argument is a LISP form. Returns the 
(destructively) translated form. The translation 
listing is dumped to the primary output file. 

Argument is a list of function names whose 
interpreted definitions are destructively 
translated. Listing to primary output file. 

transform and transorfns can be used to translate expressions that are already 
in core, whereas transor itself only works on files. 

The Translation Notes 

The translation notes are a catalog of changes made in the user's code, end of 
problems which require, or may require, further attention from the user. This 
catalog consists of two cross-indexed sections: an index of forms and an index 
of notes. The first tabulates all the notes applicable to any fomi, whereai» 



transorC sourcefile ] 



transorf orm[ f orm] 



transorfnsC fnlst] 
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the second tabulates all the forms to which any one note applies. Forms appear 
in the index of forms in the order in which they were encountered, i.e. the 
order in which they appear on the source and output files. The index of notes 
shows the name of each note, the entry numbers where it was used, and its text, 
and is alphabetical by name. The following sample was made by translating a 
small test file written in SRI LISP. 



A1.5 



LISTING FROM TRANSORING OF FILE TESTFILE.;5 
DONE ON l-NOV-71 20:10:47 



INDEX OF FORNS 

1. APPLY/EVAL at 
[DEFINEQ 

(FSET (LAMBDA & 

(PROG ...3... 

(SETQ Z (COND 

((ATOM (SETO — )) 



- ] 
2. APPLY/EVAL at 
[DEFINEQ 

(FSET (LAMBDA & 
(PROG 



(COND 

((ATOM (SETQ Y (NLSETQ "(EVAL W)"))) 

-) 
")) 

")) 



3 



3... 
(SETQ Z (COND 

((ATOM (SETQ — )) 
• (COND 

((ATOM (SETQ --)) 

"(EVAL (NCONS W))") 
--)) 

-)) 



MACHINE-CODE at 
[DEFINEQ 

(LESSl (LAMBDA & 

(PROG ...3... 
(COND 
...2... 

((NOT (EQUAL (SETQ XZ "(OPENR (MAKNUM & -))• 
) 

-)) 

--)) 

- 3 
MACHINE-CODE at 
[DEFINEQ 

(LESSl (LAMBDA & 

(PROG ...3... 
(COND 
. . .2 . . . 

((NOt'(EQUAL & (SETQ Y2 

"(OPENR (MAKNUM & —.))"))) 

-)) 



INDEX OF NOTES 

APPLY/EVAL at 1, 2. 

TRANSOR will translate the arguments of the APPLY or EVAL expression, but 
the user must make sure that the run-time evaluation of the arguments returns a 
BBN-compatible expression. 
MACHINE-CODE at 3» 4. 

Expression dependent on machine-code. User must recode. 
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The translation notes are generated by the transformations used, and therefore 
reflect the Judgment of their author as to what should be included. 
Straightforward conversions are usually made without comment; for example, the 
DEFPROP's in this file were quietly changed to OEFINEQ's. transor found four 
noteworthy forms on the file, and printed an entry for each in the index of 
forms, consisting of an entry number, the name of the note, and a printout 
showing the precise location of the form. The form appears in double-quotes 
and is the last thing printed, except for closing parentheses and dashes. An 
ampersand represents one non-atomic element not shown, and two or more elements 
not shown are represented as ...n..., where n is the number of elements. Note 
that the printouts describe expressions on the output file rather than the 
source file; in the example, the DEFPROP's of SRI LISP have been replaced with 
DEFINEO's. 

Errors and Messages 

transor records its progress through the source file by teletype printouts 
which identify each expression as it is read in. Progress within large 
expressions, such as a long OEFINEQ, is reported every three minutes by a 
printout showing the location of the sweep. 

If a transformation fails, transor prints a diagnostic to the teletype which 
identifies the faulty transformation, and resumes the sweep with the next form. 
The translation notes will identify the form which caused this failure, and the 
extent to which the form and its arguments were compromised by the error. 

If the transformation for a common function fails repeatedly, the user can type 
control-H. When the system goes into a break, he can use transorset to repair 
the transformation, and even test it out (see TEST command, page Al.li). He 

may then continue the main translation with OiC. 
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Transorset 



To use transorset , typo transoj-set ( ) to INTERLISP. transorset will respond 
with a sign, its prompt character, and await input. The user is now in an 
executive loop which is like evalqt with some extra context and capabilities 
intended to facilitate the writing of transformations, transorset will thus 
progress apply and eval input, and execute history commands Just as evalqt 
would. Edit commands, however, are interpreted as additions to the 
transformation on which the user is currently working, transorset always saves 
on a variable named currentfn the name of the last function whose 
transformation was altered or examined by the user, currentfn thus represents 
the function whose transformation is currently being worked on. Whenever edit 
commands are typed to the ^ sign, transorset will add then to the 
transformation for currentfn . This is the basic mechanism for writing a 
transformation. In addition, t ransorset contains commands for printing out a 
transformation, editing a transformation, etc., which all assume that the 
command applies to currentfn if no function Is specified. The following 
example illustrates this process.. 
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*-TRANSORSET( ) 

+FN TCONC 

TCONC 

+(SW 2 3) 

♦ TEST (TCONC A B) 

P 

(TCONC B A) 
+TEST (TCONC X) 

TRANSLATION ERROR: FAULTY TRANSFORMATION 
TRANSFORMATION: ((SW 2 3)) 
OBJECT FORM: (TCONC X) 



1 . TRANSFORMATION ERROR AT 
"(TCONC X)" 



(TCONC X) 

+ (IF (## 3) ((SW 2 3)) ((-2 NIL] 

♦SHOW 

TCONC 

[(SW 2 3) 
(IF (## 3) 

((SW 2 3)) 
((-2 NIL] 

TCONC 

+ERASE 

TCONC 

+REDO IF 

+SHOW 

TCONC 

[(IF (## 3) 

((SW 2 3)) 

((-2 NIL] 

TCONC 
+TDST 
= TEST 

(TCONC NIL X) 
+ 
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In this example, the user begins by using the FN command to set currentfn to 
TCONC [1]. He then adds to the (empty) transformation for tconc a command to 
switch the order of the arguments [2] and tests the transformation [3]. His 
second TEST [4] falls, causing an error diagnostic [5] and a translation note 
[6]. He writes a better command [7] but forgets that the original SW command 
is still in the way [8]. He therefore deletes the entire transformation [91 
and redoes the IF [10]. This time, the TEST works [11]. 

Transorset Commands 

The following commands for manipulating transformations are all lispxmacros 
which treat the rest of their input line as arguments. All are undoable. 

FN Resets currentfn to its argument, and returns the 

new value. In effect FN says you are done with 
the old function (as least for the moment) and 
wish to work on another. If the new function 
already has a transformation, the^ message 
(OLD TRANSFORMATIONS) is printed, and any 
edltconroands typed in will be added to the end of 
the existing commands. FN followed by a carriage 
return will return the value of currentfn without 
changing it. 

SHOW Command to prettyprint a transformation. SHOW 

followed by a carriage return will show the 
transformation for currentfn . and return currentfn 
as its value. SHOW followed by one or more 
function names will show each one in turn, reset 
currentfn to the last ono, and return the new 
value of currentfn. 
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EDIT Command to edit a transformation. Similar to SHOW 

except that instead of prettyprinting the 
transformation, EDIT gives it to edlte. The user 
can then work on the transformation until he 
leaves the editor with OK. 

ERASE Command to delete a transformation. Otherwise 

similar to SHOW. 

TEST Command for checking out transformations. TEST 

takes one argument » a form for translation. The 
translation notes, if any» are printed to the 
teletype, but in an abbreviated format which omits 
the index of notes. The value returned is the 
translated form. TEST saves a copy of its 
argument on the free variable testform , and if no 
argument is given, it uses testform , i.e. tries 
the previous test again. 



DUMP Command to save your work on a file. DUMP takes 

one argument, a filename. The argument is saved 
on the variable dumpfile , so that if no argument 
is provided, a new version of the previous file 
will be created. 

The DUMP command creates files by makefile . Normally flleFNS will be unbound, 
but the user may set it himself; functions called from a transformation by the 
E command may be saved in this way. DUMP makes sure that the necessary command 
is included on the fileVARS to save the user's transformations. The user may 
add anything else to his fileVARS that he wishes. When a transformation file 
is loaded, all previous transformations are erased unless the variable merge is 
set to T. 
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EXIT 



transorset returns NIL. 



The REMARK Feature 

The translation notes are generated by those transformations that are actually 
executed via an editmacro called REMARK. REMARK takes one argument* the name 
of a note. When the macro is executed, it saves the appropriate information 
for the translation notes, and adds one entry to the index of forms. The 
location that is printed in the index of forms is the editor's location %fhen 
the REMARK macro is executed. 

To write a transformation which makes a new note, one must therefore do two 
things: define the note, i.e. choose a new name and associate it with the 
desired text; and call the new note with the REMARK macro, i.e. insert the edit 
command (REMARK name) in some transformation. The NOTE command, described 
below, is used to define a new note. The call to the note may be added to a 
transformation like any other edit command. Once a note is defined, it may be 
called from as many different transformations as desired. 

The user can also specify a remark with a new text, without bothering to think 
of a name and perform a separate defining operation, by calling REMARK with 
more than one argument, e.g. (REMARK text-of-remark) . This is interpreted to 
mean that the arguments are the text, transorset notices all such expressions 
as they are typed in, and handles naming automatically; a new name is 
generated^ and defined with the text provided, and the expression itself is 
edited to be (REMARK generated-name). The following example illustrates the 
use of REMARK. 



The name generated is the value of currentfn suffixed with a colon, or with 
a number and a colon. 
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-TRANSORSET( ) 

+NOTE GREATERP/LESSP (BBN'S GREATER? AND LESSP ONLY [1] 
TAKE TWO ARGUMENTS, WHEREAS SRI'S FUNCTIONS TAKE AN 
INDEFINITE NUMBER. AT THE PLACES NOTED HERE, THE SRI CODE 
USED MORE THAN TWO ARGUMENTS, AND THE USER MUST RECODE.] 

GREATERP/LESSP 
-•■FN GREATERP 
GREATERP 

■»^(IF (IGREATERP (LENGTH (##))3) NIL ((REMARK GREATERP/LESSP] [2] 
+FN LESSP 

LESSP 

♦REDO IF [3] 

•f SHOW 

LESSP 

[(IF (IGREATERP (LENGTH (##)) 
3) 

NIL 

((REMARK GREATERP/LESSP] 

LESSP 
+FN ASCII 

(OLD TRANSFORMATIONS) 

ASCII 

•♦■(REMARK ALTHOUGH THE SRI FUNCTION ASCII IS IDENTICAL [4] 
TO THE BBN FUNCTION CHARACTER. THE USER MUST MAKE SURE THAT 
THE CHARACTER BEING CREATED SERVES THE SAME PURPOSE ON BOTH 
SYSTEMS, SINCE THE CONTROL CHARACTERS ARE ALL ASSIGNED 
DIFFRENTLY.] 

+SHOW [5] 
ASCII 

((1 CHARACTER) 
(REMARK ASCII:)) 
ASCII 

+NOTE ASCII: [6] 

EDIT 

*NTH -2 

*P 

... ASSIGNED DIFFRENTLY.) 
*(2 DIFFERENTLY.) 

OK 

ASCII: 
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In this example, the user defines a note named GREATERP/LESSP by using the NOTE 
command [1], and writes transformations which call this note whenever the sweep 
encounters a GREATERP or LESSP with more than two arguments [2-3]. Next, the 
implicit naming feature is used [4] to add a REMARK command to the 
transformation for ASCII, which has already been partly written. The user 
realizes he mistyped part of the text, so he uses the SHOW command to find the 
name chosen for the note [8]. Then he uses the NOTE command on this name, 
ASCII:, to edit the note [6]. 

NOTE First argument is note name and must be a literal 

atom. If already defined, NOTE edits the old 
text; otherwise it defines the name, reading the 
text either from the rest of the input line or 
from the next line. The text may be given as a 
line or as a list. Value is name of note. 

The text is actually stored, as a comment, i.e. a * and XX are added in front 
when the note is first defined. The text will therefore be lower-cased the 
first time the user OUMPs (see Section 14). 

DELNOTE Deletes a note completely (although any calls to 

it remain in the transformations). 

Controlling the Sweep 

transor's sweep searches in print-order until it finds a form for which a 
transformation exists. The location is marked, and the transformation is 



On the global list usernotes. 
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executed. The sweep then takes over again, beginning from the marked location, 
no matter where the last command of the transformation left the editor. User 
transformations can therefore move around freely to examine the context, 
without worrying about confusing the translator. However, there are many cases 
where the user wants his transformation to guide the sweep, usually in order to 
direct the processing of special forms and FEXPR's. For example, the 
transformation for QUOTE has only one objective: to tell the sweep to skip over 
the argument to QUOTE, which is (presumably) not a LISP form. NLAN is an 
editroacro to permit this. 

NLAM An atomic editmacro which sets a flag which causes 

the sweep to skip the arguments of the current 
form when the sweep resumes. 

Special forms such as cond, prog , selectq , etc., present a more difficult 
problem. For example, (COND (A B)) is processed Just like (FOO (A B)): i.e. 
after the transformation for cond finishes, the sweep will locate the "next 
form," (A B), retrieve the transformation for the function A, if any, and 
execute it. Therefore, special forms must have transformations that preempt 
the sweep and direct the translation themselves. The following two atomic 
editroacros permit such transformations to process their forms, translating or 
skipping over arbitrary subexpressions as desired. 

DOTHIS Translates the editor's current expression, 

treating it as a single form. 

DOTHESE Translates the editor's current expression, 

treatinig it as a list of forms. 
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For example, a transformation for setq might be (3 OOTHIS). This translates 
the second argument to a setq without translating the first. For cond , one 
might write (1 (LPQ NX DOTHESE)), which locates each clause of the CONO in 
turn, and translates it as a list of forms, instead of as a single form. 

The user who is starting a completely new set of transformations must begin by 
writing transformations for all the special forms. To assist him in this and 
prevent oversights, the file <LISP>SPECIAL.XFORNS contains a set of 
transformations for LISP special forms, as well as some other transformations 
which should also be included. The user will probably have to revise these 
transformations substantially, since they merely perform sweep control for 
INTERLISP, i.e. they make no changes in the object code. They are provided 
chiefly as a checklist and tutorial device, since these transformations are 
both the first to be written and the most difficult, especially for users new 
to the INTERLISP editor. 

« « ft 

When the sweep mechanism encounters a form which is not a list, or a form car 
of which is not an atom, it retrieves one of the following special 
transformations. 

NLISTPCOMS Global value is used as a transformation for any 

form which is not a list. 

For example, if the user wished to make sure that all strings were quoted, he 
night set nlistpcoms to. 

((IF (STRIN6P (##)) ((ORR ((- OUOTE))((HBO QUOTE)))) NIL)). 



Recall that a transformation is a list of edit commands. In this case, 
there are two commands, 3 and OOTHIS. 
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LAMBDACOHS Global value is used as a transformation for any 

form, car of which is not an atom. 

These variables are initialized by <LISP>SP£CIAL.XFORNS and are saved by the 
DUMP command, nlistpcoms is initially NIL, mailing it a NOP. lambdacoms is 
initialized to check first for open LAMBDA expressions, processing them without 
translation notes unless the expression is badly formed. Any other forms with 
a non-atomic car are simply treated as lists of forms and are always mentioned 
in the translation notes. The user can change or add to this algorithm simply 
by editing or resetting lambdacoms. 
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The INTERLISP Interpreter 

The flow chart presented below describes the operation of the INTERLISP 
interpreter, and corresponds to the Pi-expression definition of the LISP 1.5 
interpreter to be found in the LISP 1.5 manual, [NcCl]. Note that car of a 
form roust be a function; it cannot evaluate to a function. 

car of a form is atomic, its function cell must contain 

(a) an S-expression of the form (LANBDA ...) or (NLAHBOA ...); or 

(b) a pointer to compiled code; or 

(c) a SUBR definition (see Section 8); 
Otherwise the form is considered faulty. 

If car of a form is an S-expression beginning with LANBDA or NLANBOA, the 
S-expression is the function. If car of the form begins with FUNAR6, the 
funarg mechanism is invoked (see Section 11). Otherwise the form is faulty. 
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i 



ENTER EVAL WITH FORM 





SET D 




CONTENTS 


OF 


DEFINI TION 


CELL 



YES 



RETURN 
BINDING 



RETURN 
FAULTEVAL [FORM] 




CALL SUBR, 
COMPILED CODE, 
OR EXPR 



RETURN 
FAULTEVAL [FORm] 



FIGURE A2-I 

Note: variables c and d are for description only; they are not actually bound 
as variables. ~ 
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Control Characters 



Several teletype control characters are available to the user for communicating 
directly to INTERLISP, i.e.» not through the read program. These characters 
are enabled by INTERLISP as interrupt characters, so that INTERLISP immediately 
'sees' the characters, and takes the corresponding action as soon as possible. 
For example, control characters are available for aborting or interrupting a 
computation, changing the printlevel, returning to TENEX, etc. This section 
summarizes the action of these characters, and references the appropriate 
section of the manual where a more complete description may be obtained. 



Control Characters Affecting the Flow of Computation 

1. control-H (interrupt) at next function call, INTERLISP goes into 

a break. Section 16. 

2. control-B (break) computation is stopped, stack backed up to the 

last function call, and a break occurs. Section 16. 

3. control-E (error) computation is stopped, stack backed up to the 

last errorset , and NIL returned as its value. Section 
16. 

4. control-D (reset) computation is stopped, control returns to 

evalqt . 

5. control-C (TENEX) computation is stopped, control returns to 

TENEX. Program can always be continued without any ill 
effect with TENEX CONTINUE command. 



If typed during a garbage collection the action of control-B, control-E» and 
control-D is postponed until the garbage collection Is completed. 



Typing control-E and control-D causes INTERLISP to clear and save the input 
buffers. Their contents can usually be recovered via the SBUfS (alt-modeBUFS) 
command, as described In Section 22. 



I/O Control Characters 

1. rubout clears teletype input buffer. For example, rubout 

would be used if the user typed ahead while in a 
garbage collection and then changed his mind. Section 
2. A bell Is rung when the buffer has been cleared, so 
that the user will know when he nay begin typing again. 
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Note: a sudden burst of noise on a telephone line frequently causes INTERLISP 
to receive a rubout, since the code for rubout is 177Q, i«e. all i's. This 
causes INTERLISP to (mistakenly) clear the input buffer and ring a bell. If 
INTERLISP seems to be typing many spurious bells, it is a good indication that 
you have a bad connection. 



2. control-0 

3. control-P 

4. control-A, Q 

5. control-R 

Miscellaneous 
1. control-T 



2. control-S 

3. control -U 



clears teletype output buffer. Sections 2 and 14. 

changes printlevel. Section 14. 

line editing characters, Sections 2 and 14. 

causes INTERLISP to retype the input line, useful after 
several control-A's» e.g., 

user types: «'OEFINEQ((LANOA\A\OBA\Acontrol-R 
INTERLISP types: OEFINEQ((LANB 



(time) prints total execution time for program, as well 
as its status, e.g., 

«-RECLAIM( ) 

GC: 8 

RUNNING AT 15272 USED 0:00:04.4 IN 0:00:39 

1933, 10109 FREE WORDS 

10109 

10 WAIT AT 11623 USED 0:00:05.1 IN 0:00:49 

(storage) change minfs. Section 10. 

if typed in the middle of an expression that is being 
typed to evalqt . breakl or the editor, will cause the 
editor to be called on the expression when it is 
finished being read. See Section 22. 
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Nttmes of functions are in upper case, followed by their arguments enclosed in 
square brackets [}. e.g. ASSOCCX;Y]. The FNTYP for SUBRs is printed in full; 
for other functions, ML indicates an NLAMBDA function, and * a nospread 
function, e.g. LISTFILES[FILES] NL* indicates that LISTFILES is an NLAMBDA 
nospread function. Words in upper case not followed by square brackets are 
other INTERLISP words (system parameters, property names, messages, etc. ) • 
Words and phrases in lower case are not formal INTERLISP words but are general 
topic references. 
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ALAMS (compiler variable/parameter) 18.6 

ALIAS (property name) 15.17,22 

ALL (use in prettydef PROP command) 14.33 
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ALLCALLS[FN;TREELST] 20.9 

ALIPROP 5.9; 8.7; 22.55 

ALLPROP (os argument to load) 14.27 

ALPHORD[:R| A;B] 6.11 

ALREADY UNDONE (typed by system) 22.22,59 

olt-modc (in spelling correction) 17.11,25 

ALWAYS (clisp iterative statement operator) 23.20 

AMAC (property name) 18.35,37 

AMBIGUOUS (typed by dwim) 17.11 

AND[X1 ;X2; . . , ;Xn] F5UBR* 5.12 

AND (In event specification) 22.13 

AND (in USE command) 22.14 

ANTIL06[X] 13.8 

APPENDCL] « 6.1 

APPLY[FN;ARGS] SUBR Ls -9 ;) 1 1 . 1 , 

16.2; laTZt)"^ 

apply format 2.4 

APPLY*[FN;ARG1 ; . . . ;ARGn] SUBR* 2.3; 8.10; 11.1; 16.2, 

18.20 

approval (of dwim corrections) 17.3,5,25 

APPROVEFLG (dwim variable/parameter) 17.5,18,25,27 

ARCCOS[X:RADIANSFLG] 13.9 

ARCCOS: ARG NOT IN RANGE (error message) 13.9 

ARCHIVE (prog. asst. command) 22.27 

ARCIIIVFFN (prog. asst. variable/parameter) 22.27,33-34 

ARCHIVELST (prog. asst. variable/parameter) 22.44,53 

ARCSIN[X;RADIANSFLG] 13.9 

ARCSIN: ARG NOT IN RANGE (error message) 13.9 

ARCTAN[X;RADIANSFLG] 13.9 

ARGrVAR;M] FSUBR 4.2; 8.11; 16.10 

ARG NOT ARRAY (error message) 10.13-14; 16.10 

ARG NOT ATOM (error message) 7.1-2; 16.8 

ARG NOT ATOM - SET (error message) 5.8-9; 16.8 

ARGLIST[X] , 2.3; 8.1,3-4,6; 15.10 

ARGS (break command) 15.8,10 

ARGS NOT AVAILABLE (error message) 8.6 

ARGTYPE[FN] SUBR 8.1-5 

argument evaluation 4.1-2 

argument list 4.1; 8.1 

arithmetic functions 13.2-10 

AROUND (as argument to breakin) 15.7,19-20 

ARRAY[N;P;V] SUBR 3.8; 10.12 

ARRAY (prettydef command) 14.33 

array functions 10.12-14 

array header 3.8; 10.12 

army pointer 3.8 

ARRAYPCX] SUBR 5.11; 10.13 

ARRAYRECORD (record package) 23.53 

arrays 3.1,8,11,13; 5.11 

ARRAYS FULL (error message) 10.13; 16.9 

ARRAYSIZECA] 10.13 

AS (clisp iterative statement operator) 23.25-26 

ASSEMBLE 4.3; 13.13; 18.34-35, 

46 

ASSEMBLE macros 18.37 

ASSEMBLE statements 18.35-39 

assignments (in pattern match compiler) 23.43 
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assignmonts (in clisp) 23.12 

ASSOC[X;Y] ^ , 5.15 

association list 12.1-2 

ATOM[X] SIJBR 5.11 

ATOM HASH TABLE FULL (error message) 16.8 

ATOM TOO LONG (error message) 10.2,7; 16.8 

ATOMRECORD (record package) 23.52 

atoms 3.1,11 

ATTACH[X;Y] 6.3 

ATTEMPT TO RPLAC NIL (error message) 5.2-3; 6.4; 16.8 

ATTEMPT TO SET NIL (error message) 5.8; 16.8 

(B cl ... em) (edit command) 9.13,39-40 

backtrace 2.8; 12.2,4; 15.9 

24 

backtracking 22.60 

BAD ARGUMfNT - FASSOC (error message) 2.3; 5.15 

BAD ARGUMENT - FGETD (error message) 8.3 

BAD ARGUMENT - FLAST (error message) 2.3; 6.7 

BAD ARGUMENT - FLENGTH (error message) 2.3; 6.8 

BAD ARGUMENT - EMEMB (error message) 2.3; 5.14 

BAD ARGUMENT - FNTM (error message) 2.3; 6.8 

BAD PRETTYCOM (prettydef error message) 14.36 

BAK:TRACE[ER0M;T0;SKIPFN;VARSFLG;*F0RM*FLG;ALLFL6]. 15.24 

BCOMPL[FILES;CFILE;NOBLOCKSFL63 14.44,46; 18.26,28 

30-32 

BEFORE (prog. asst. command) 22.22,26,34 

BEFORE (as argument to advise) 19.4-6 

BEFORE (as argument to breakin) 15.7,19-20 

BEFORE (in INSERT command) (in editor) 9.41 

BEFORE (in MOVE command) (in editor) 9.48 

boll (typod by dwim) 17.6 

bell (typed by system) 10.16; 14.20; 16.2 

A3 . 1 

boll (in history event) 22.22,33,44,49,52 

bells (typed by system) A3, 2 

(BELOW com x) (edit command) , 9.31 

(BELOW com) (edit command) ' 9.31 

BF (edit command) 9.10,28 

(BF pattern T) (edit command) 9.28 

(BI n m) (edit command) 9.8,52 

(BI n) (edit command) 9.52 

BIND (clisp iterative statement operator) 23.21 

BIND (as argument to advise) 19.7 

(BIND . coms) (edit command) 9.70 

BK (edit command) 9.10,18-19 

(BK n) (n a number, edit command) 9.19 

BKL1NBU([X] SUBR 14.21 

BKSYSBUF[X] SUBR 14.21,47; 21.24 

BLKAPPLY[FN;ARGS] SUBR 18.20 

BLKAPPLY«fFN;ARGl;...;ARGn] SUBR* 18.20 

BLKAPPLYENS (compiler variable/parameter) 18.20,26,29 

BLKLIBRARY (compiler variable/parameter) 18.21,29 

BLKLIBRARYDEF (property name) 18.21; 22.57,63 

block compiler 18.26-34 

block compiling 18.17-34 

block declarations 14.34; 18.28-32 

block library 18.21 
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BLOCKCOMPILE[BLKNAME;BLKFNS;ENTRIES;FLG] 18.26-28 

BLOCKED (typed by editor) 9.79 

BLOCKS (prettydef command) 14.34; 18.28-29 

(BO n) (edit command) 9.8,52 

BODY (use in iterative statement In clisp) 23.28 

BOTTOM (as argument to advise) 19.5,7 

box 13.14 

BOXCOUNT[TYPE;N] 5UBR 21.4 

BOXED (cdita command/parameter) 21.13 

boxed numbers 13.1 

boxing 13.1-2, 10-12 

BREAK[X3 NIL* 15.1,7,18-19,21 

BREAK (error message) 16.9 

break characters 14.12-15,19,24 

break commands 15.7-14 

break expression 15.6,12 

BREAK INSERTED AFTER (typed by breakln) 15.20 

break package 15.1-24 

BREAK0[rN;WHEN;COMS;BRKFN;TAIL] 15.16-19,21,23 

BREAK 1[BRKEXP;BRKWHEN;BRKFN;BRKC0MS;BRKTVPE] ML . 15.1-2,4,16,18-19,21, 

16.1-3,7,13; 17.28 

BREAKCMECK 16.2-7,10,12; 17.15 

BREAKDOWN[FNS] NL 21.5-7 

BREAKIN[FN;WHERE;WHEN;BRKCOMS] NL 15.2,7,17,19.21-23 

BREAKMACROS (break variable/parameter) 15.15-16 

breakpoint 15.2 

BRECOMPILt[FILES;CFILE;FNS;C0REFLG;N0BL0CKSFLG] . 14.44,46-48; 18.26,28, 

30-34 

BRKCOMS (break variable/parameter) 15.9,14-16 

BRKDWNTYPE (system variable/parameter) 21.6 

BRKDWNTYPES (system variable/parameter) 21.6-7 

BRKEXP (break variable/parameter) 15.6-7,9.11-12,14,16, 

16.1-2,4 

BRKFILE (break variable/parameter) . . . .' 15.15 

BRKFN (break variable/parameter) 15.8.16 

BRKINFO (property name) 15.16,21-22 

BRKINFOLST (break variable/parameter) 15.22-23 

BRKTYPE (break variable/parameter) 15.16 

BRKWHEN (break variable/parameter) 15.16 

BROADSCOPE (property name) 23.70 

BROKEN (property name) 8.7 

BROKEN (typed by system) 15.4,16 

(BROKEN) (typed by system) 16.4 

BROKEN-IN (property name) 8.7; 15.21-22 

BROKENFNS (break variable/parameter) 15.17.21-22; 17.28 

BT (break command) 2.8; 15.8-9 

BTV (break command) 15.8,10 

BTV! (break command) 15.10 

BTV* (break command) 15.8,10 

BY (clisp iterative statement operator) 23.22-24,27 

BY (in REPLACE command) (in editor) 9.42 

C (in an assemble statement) 18.38 

C (makefile option) 14.46 

CALLS[FN;EXPRFLG;VARSFLG] 20.10 

CAN'T - AT TOP (typed by editor) 9.5,17 

CAN'T BE BOTH AN ENTRY AND THE BLOCK NAME 

(compiler error message) 18.27,52 
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CAP (edit command) 

CAR[X] SUBR 

carriage-return 



carriage-return (edita command/parameter) 

CAUTIOUS (DWIM mode) 

CCODEPCFN 1 SUBR 

CDR[X] SUBR 

CEXPR (function type) 

CEXPR* (function type) 

CFEXPR (function typo) 

CFEXPR* (function type) 

(CHANGE G> TO ...) (edit command) 

CHANGE DINSLST (file package variable/parameter) 
CHANGEDVARSLST (file package variable/parameter).. 

CMANGFNAMf [ FN ; FROM ; TO ] 

CHANGE PROP[X; PROP 1 ;PR0P2 3 

CHANGFSLICE[N;HISTORY;L] 

CHARACTERtN] SUBR 

character atoms 

character codes 

CHC0N[X;FlG] SUBR 

CHC0N1[X] SUBR 

CH00ZrxW0RD;REL;SPLST;TAIL;TIEFLG;FN;NDBLS;CLST].. 

CIRCLMAKER[L] 

CIRCLPRINT[L;PRINTFLG;RLKNT] 

CL (edit command) 

CL-.FLG (clisp variable/parameter) 

CLDISABLE 

CLEANUPLFILES] NL* 

CLEARBUF[FILE:FLG] SUBR * 

CLISP 



CLISP interaction with user 

CLISP internal conventions 

CLISP operation 

CLISP% 

CLISP: (edit command) 

CLISPARRAY (clisp variable/parameter) .. 
CLISPCHARRAY (clisp variable/parameter) 
CLISPCMARS (clisp variable/parameter) .. 

CLISPDEC[nECLST] 

CLISPFLG (clisp variable/parameter) .... 
CLISPIFTRANFLG (clisp variable/parameter) 
CL1SPIFY[X;L] 



CLISPIFY (makefile option) 

CLISPIFYFNS[FNS] NL* 

CLISPIFYPACKFLG (clisp variable/parameter) 

CLISPIFYPRETTYFLG (clisp variable/parameter) 

CLISPIFYPRETTYFLG (prettydef variable/parameter).. 

CLISPINFIX (property name) 

CLISPINFIXES (clisp variable/parameter) 

CLISPRECORDFIELO (property name) 

CLISPTYPE (property name) 

CL0CK[N] SUBR 



9.75 
5.1 

3.2; 14.10-11,13.15-19, 
23 
21.9»12 

17.3,5,23,27; 23.5,67 
8.1,3-5 
5.1 

4.3; 8.4-5 

4.3; 8.4-5 

4.3; 8.4-5 

4.3; 8,4-5 

9 .42 
14.45,50 
14.45,50 

9.90; 15.23 

7.2 
22.8,54 
10.4 
10.2 
10.4 
10.4 
10.4 

17.20-21,26 

7.6; 21.28 

7.6; 21.26-27 

9.77; 23.76 
23.59,74 
23.74 
14.45,48 
14.21; 22.30 
11.4; 14. 4G; 18.6,8, 
21.23; 17.16-18, 
23.1-76; 20.5 
23.67 
23.68 
23.64-67 
23.31-32.75 
23.31,75 
23.31,37,72,76 
23.71 
23.71 
23.33,73 
23.71 
23 .31 , 74 

14!40,'46; 23.36,58, 

73-74 
14.46; 23.60,75 
23.74 
23.60,75 
23.75 
14.40,46 
23.70 
23.71 
23.57 
23.69 
21.3 
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CLOSEALL[] SUBR 14.4 

CLOSnF[FILE] SUBR 14.4 

CLOStR[A;X] SUBR 10.18 

CLREMPARSFLG (clisp variable/parameter) 23.59,74 

CLRMASHC ARRAY] SUBR 7.5 

CLUMPGET[OBJECT;RELATI0N;UNIVERSE] 20.17 

COpE ( property name) 8.7-8 

COLLECT (clisp iterative statement operator) .... 23.19 

COM (ns suffix to file name) 18.9,11,30 

commands that move parentheses (in editor) 9.51-54 

COMMENTTLG (prettydef variable/parameter) 14.39 

commGnts (in listings) 14.30-31,40 

compnctinq 3.13 

COMPILErX:FLG] 18.7-8 

C0NPILE1[FN;DEF] 18.8 

compiled code 10.12 

compilod file 18.8,10 

compiled functions 4.2 

C0MPILEFILES[FILES3 ML* 14.48 

compiler 4.3; 18.1-52 

compiler error messages 18.49-52 

compiler functions 18.7-13,27,30 

compiler macros 18.14-16 

compiler printout 18.48-49 

compiler questions 18.3-5 

compiler structure 18.34 

COMPIIEUSERFN (compiler variable/parameter) 18.6,13 

COMPILEUSERFN (use by clisp) 23.64 

compiling CLISP 23.63 

compiling files 18.8,10,30 

compiling FUNICTION 18.16 

compiling NLAMBDAs 18.5-6 

COMPROP (prettydef command) 14.35; 18.9 

COMPROP* (prettydef command) 14.35; 18.9 

COMPSET[FILE;FLG] 18.3 

computed macros 18.15 

COMS (prettydef command) 14.35 

(COMS xl ... xn) (edit command) 9.63 

(COMSQ . coms) (edit command) 9.64 

C0NCAT[Xl:X2;...;Xn] SUBR« 3.10; 10.7,12 

COND[Cl:C2;...;Cn3 FSUBR* 4.4; 5.4 

cond clause 5.4 

CONS[X;Y] SUBR 3.7.11; 5.1 

cons alqorithm 5.2 

CONSCOUNT{N] SUBR 5.2; 10.18; 21.4 

constructing lists (in clisp) 23,16 

CONTIN (prog. asst. command) 21.21; 22.34 

CONTINUE (tenex command) 2.4,9; 21.4,19; A3.1 

CONTINUE SAVING? (typed by system) 22.39,57 

CONTINUE WITH T CLAUSE (typed by dwim) 17.9 

continuing an edit session 9.72-74 

CONTROLtU] SUBR 2.5; 14.11,14,23 

control characters 2.4-5; A3. 1-2 

control pushdown list 12.2 

control-A 2.4; 14.10,12,14-15,23, 

25 

control-B 16.3,5,7,9; 21.3; A3.1 
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control-C 
control-D 



control-E 



control-F 
control-H 



control-O 
control-P 
control-Q 



control-R 

control-S ... 

control-T 

control-U 

copy 

COPY[X] 

COPYING (record package) 
COREVAL (property name) 



CORrVALS 

COREVALS ( system variable/parameter) .... 

C0,SrX;RADIANSFLG3 

COUNTtX] 

COUNT (cllsp iterative statement operator) 

CPLISTS[X;Y] 

CQ (in an assemble statement) 

CREATE (record package) 

current expression (in editor) 

CURRENTEN (transor variable) 

data types 

data-paths (In records in clisp) 

DATE[ ] SUBR 

DCHCON[X;SCRATCHLIST;FLG] 

DDT[ ] SUBR 

debugging 

declarations (in clisp) * 

DECLARE[X] FSUBR 

DECLARE 



DEFINE[X] 

DEEINEOrX] NIL* 

defininn now iterative statement operators 

DEFLIST[L;PROP] 

DELETE (edit command) 

(DELETE . (3) (edit command) 

DELNOTE (transor command) 

DESTINATION IS INSIDE EXPRESSION BEING MOVED 

(typed by editor) 

destructive functions 

DFNFLG (system variable/parameter) 



DIFFERENCE[X;Y3 



2.4; 21.4,18-19; A3.1 
2.4; 5.10; 9.71; 14.21, 

15.6,16; 16.2.7,13, 

18.7; 21.3; 22.30, 

A3.1 

9.3; 14,21; 15.6,20. 
16.3,13; 21.3,10; 22.30, 
A3.1; 17.6-7,14 
14.2 

10.17; 14.21; 15.16, 
16.2-3 

2.4; 14.20; A3. 2 
14.20-21; 15.10 

2.4; 14.10-12,14-15,23, 
25 
A3 . 2 

lo!l6; 14.21 
A3. 2 

2.5; 22.32,50 

6.1,4-5,7 

6.4 
23.56 

18.39,41-42; 21.3-4, 

10-11 
18.39-40 
18.39 
13.9 

6.8 
23.20 

6.12 
18.38 

23.60-51.55 

9.2,4,8,11-15,23 
A1.8 

3.1-11 
23.49 
21,2 
10.4 
21 .8 

2.8; 12.2; 15.1; 20.5 
23.13,16.33,45,63 
18.9 

14.34-35; 18.9,11,14,29, 

31-32 

2.6; 8.6-7 

2.6; 8.7 
23.28 

7.3; 14.33; 18.9 

9.14,37,40,42 

9.42 
A1.14 

9.49 
6.4-5 

5.9; 8.7-8; 14.27, 
22.43,55 
13.7 
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DIR (prog. asst. command) 22.34 

DIRECTORY FULL (error message) 16.9 

disabling a CLISP operator 23.61 

DISMISSLN] 21.3 

DMPMASM[L] NL* 7.6 

DO (clisp Iterative statement operator) 23.19 

DO (edit command) 22.31,61 

DO (prog. asst. command) 22.31 

DONELST ( printstructure variable/parameter) 20.8 

dot notation 2.1 

DOTHESE (transor command) A1.15 

DOTMIS (transor command) Al.lS 

dotted pair 5.1 

DRCM0VE[X;L3 6.4 

DREVERSECL] 6.4 

DSIIBST[X;Y;Z] 6.5,7 

DUMP (transorset command) Al.ll 

DUNPACK[X;SCRATCHLIST;FLG3 10.3 

DW (edit command) 9.77; 23.76 

DW (error message) 17.23 

DWIMCX] 17.5,23 

DWIM 2.6; 14.44; 16.1, 

21.23; 22.23; 17.1-28 

DWIM interaction with user 17.5 

DWIM variables 17.19 

DWIMFLG (dwim variable/parameter) 17.5,12,27 

DWIMFLG (system variable/parameter) 9.80,85-86 

DWIMIFY[X;L] 14.46; 17.23; 23.61-64, 

72-74; 20.5 

DWIMIFYCOMPFLG (clisp variable/parameter) 23.63,73 

DWIMIFYCOHPFLG (compiler variable/parameter) 18.8 

DWIMIFYFNSCFNS] NL« 23.62,73 

DWIMUSERFN (dwlm variable/parameter) 17.16-19 

DWIMWAIT (dwim variable/parameter) 22.39; 17.6,8 

ECXEEEE] ML* 8.9 

E (edit command) 9.9,62; 22.62 

E (in an assemble statement) 18.38 

E (prettydef command) 14.34 

E (in a floating point number) 3.6; 14.11 

E (use in comments) 14.40 

(E X T) (edit command) 9.62 

(E x) (edit command) 9.62 

EACHTIME (clisp iterative statement operator) ... 23.25-26 

EDIT (break command) 15.8,11-13 

EDIT (transorset command) Al.ll 

EDIT (typed by editor) 9.83 

edit chain 9.4,7,11-13,15,23 

edit commands that search 9.21-33 

edit commands that test 9.64 

edit macros 9.67-70 

EOIT-SAVE (property name) 9.72 

E0IT4n[PAT;X;CHANGEFLG] . 9.88 

EDITAtEDITARRY;COMS] 21.8-17 

EDITCOMSA (editor variable/parameter) 9.80,82; 17.16,18 

EDITCOMSL (editor variable/parameter) 9.80-82; 17.17-18 

EDITDEFAULT 22.61; 17.5 

EDITDEFAULT (in editor) 9.80-83 
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EDITFrEXPR;COMS;ATM] 9.1,83,86-87 

EDITF[X] ML* 9.1,84-86; 14.44 

EDITFTNnP[X;PAT;FLG] 9.89 

EDITFNSrXl ML* 9.87-88 

EOITFPAT[PAT;FLG] 9.89 

EDITHISTORY (editor variable/parameter) 22.44,49,60-62 

editing arrays 21.8-17 

editing compiled code 21.8-17 

editing compiled functions 9.90; 15.23 

EDITL[ L:COMS;ATM;MESS] 9.83-84 

EDI TLO[ L ;COMS ;MESS ;EOITLFLG] 9 .84 

EDITPrX] NIL* 9.1,85,87 

EDITQUIETFLG (editor variable/parameter) 9.22 

EOITRACFFN 9.90-91 

EDITUSEKFN 9.80 

EDITVLEDITVX] NL« 9.1,85-86; 14.44 

element patterns (in pattern match compiler) .... 23.39-40 

ELT[A;N] SIJBR 3.8; 10.13; 16.10 

ELTO[A;N] SUBR 3.8; 10.14 

(EMBED @ IN ...) (edit command) 9.48 

END OF FILE (error message) 14.6,10; 16.9 

cnd-of-line 3.2; 14.6,10,13,18 

ENDFILECYl 14.38 

ENTRIES (compiler variable/parameter) 18.29 

entries (to a block.) 18.18,27 

ENIRY#[HIST;X] 22.54 

EOCX;Y] SUBR 2.3; 5.11 

eq 2.3; 21.24 

EQPrX;Y] SUBR 3.5; 5.12; 13.2,4,6 

EQUAL[X;Y] 2.3; 5.12; 13.2 

cqunl 2.3 

ERASE (transorset command) Al.ll 

E RROR[ MESS 1 ; MESS2 ; NOBREAK ] 16.6,9-10.12 

ERROR (error message) 16.9 

ERROR (property name) 22.24,45 

error correction 17.1-28 

error handling 16.1-14 

error number , 16.7 

error types 16.7 

ERRORfi] SUBR 5.9; 6.5; 15.7, 

16.12-13 

ERRORMESSCU] 16.7,13 

ERRORNC ] SUBR , 16.7, 13 

errors (in editor) 9.3 

errors in iterative statements 23.27 

ERR0RSE1[U;V] SUBR 5.9; 7.7; 16.5-6,12-14, 

17.15 

ERRORTYPELST (system variable/parameter) 16.10-11 

ERRORX[ERXM] 16.12 

ERSETOCERSETX] NL 5.8; 16.14; 18.16 

ERSTR[ERN;ERRFLG] 21.22 

ESCAPE[FLG] SUBR 14,13-14 

escape character 2.6; 3.2; 14.10 

EStlBSTrX;Y;Z;ERR0RFLG;CHARFL6] 6.5,7; 9.89; 22.14 

EVAL[X] SUBR 2.4,6; 4.2; 8.9; 16.14 

EVAL (break command) 15.7,14,16.20; 16.3-4 

eval format 2.4 
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oval-blip 12.4; 16.5 

EVALA[X;A] SUBR 8.10; 16.10 

EVALOT[CHAR] 15.5 

EVALQT 2.4 

EVALV[VAR;POS] 12.10 

event address 22.12-13 

event number 22.8,12,21,33,54 

event specification 22.11-14,19-21 

E VERY[ EVERYX ; EVERYFNl ;EVERYFN2 ] 5.13 

EV0[X3 18.19 

(EXAM . x) (edit command) 9.66 

EXEC (prog. asst. command) 21.21; 22.34 

EXEC 21.21,24 

EXIT (transorset command) A1.12 

EXPR (function type) 4.3; 8.4-8 

EXPR (property name) 9.85,88; 14.27; 18.7 

21; 17.17-18; 20.7 

EXPR* (function type) 4.3; 8.4-5 

EXPRFLG (printstructure variable/parameter) 20.6,9 

EXPRP[FN] SUBR 8.1,3-6 

exprs 4.1 

EXPTrM;N3 13.8 

(EXTRACT G»l from . 02) (edit command) 9.46 

F (edit command) 9.6,25-26 

F (response to compiler question) 18.2,4 

F (in event address) 22.12 

F pattern (edit command) 9.25 

(F pattern N) (edit command) 9.26 

(F pattern n) (n a number, edit command) 9.26 

(F pattern T) (edit command) 9.26 

(F pattern) (edit command) 9.27 

F/L 17.17 

(F= ...) (edit command) 9.27 

false 5,4 

FASSOC[X;Y] 2.3; 5.15 

FAST (makefile option) 14.46 

fast symbolic dump 14.40 

FASTCALL (in an assemble statement) 18.38 

FASTYPEFLG (dwim variable/parameter) 17.23 

FAULT IN EVAL (error message) 16.9 

FAULTAPPLY[FAULTFN;FAULTARGS] 16.2; 18.25; 17.5.14- 

19 

FAULTEVALrFAULTX] ML* 16.1,9; 17.5.14-15,19 

FCHARACTER[N] SUBR 10.4 

FETCH (use in records In clisp) 23.57 

FEXPR (function type) 4.3; 8.4-5 

FEXPR* (function type) 4.3; 8.4-5 

FGETD[X] 8.3 

FGTP[X;Y] SUBR 13.6 

FILDIR[FILE6R0UP;F0RMATFLG] 21.21 

FILE (edita command/parameter) 21.13 

FILE (property name) 14.44-45 

FILE INCOMPATIBLE - SYSIN (error message) 16.9 

file names 14.2-3 

FILE NOT COMPATIBLE (error message) 14.26 

FILE NOT FOUND (error message) 14.3; 16.9 

FILE NOT OPEN (error message) 14.3-4,8; 16.8 
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filo pnckngo 

file pointer 

FILE WON'T OPEN (error message) 

FILE: (compiler question) 

FILECRFATLD 

FILEDATE (property name) , 

FIIEOLF (property name) 

filePMS 

FILEFNSLSTCFILE] 

FILEGROUP (property name) 

FILELST (file package variable/parameter) 
FILEPKGFLG (file package variable/parameter) 

FIIEPOS[X;FILE;START;ENO;SKIP;TAIL] 

files 

FILES?[] 

FILETYPE (property name) 

fileVARS 

FINALLY (clisp iterative statement operator) 
FIRST (clisp iterative statement operator) 

FIRST (as argument to advise) 

FIRSTCOL (prettydef variable/parameter) ... 

FIRSTENfFN] 

FIRSTNAME (system variable/parameter) 

FIX[X] 

FIX (prog. asst. command) 

fixed number of arguments 

FIXP[X] 

FIXSPELL[XWORD;REL;SPLST;FLG;TAIL;FN;CLST; 

APPROVALFLG] 

FLASTfX] 

FLENGTHLX] 

FLOAT[X] 

floating point arithmetic 

floating point numbers 



FLOATPfX] 5UBR 

FLTFMUN] SUBR 

FMEMB[X;Y] 

FMiNUSfX] 

FN (transorset command) 

(fn - NO BREAK INFORMATION SAVED) 

(fnl IN fn2) 

(fnl NOT FOUND IN fn2) 

fnl-INf-fn2 

FNCIIECKrFN;NOMESSFLG;SPELLFLG;PROPFLG] 

FNS (prettydef command) 

FNTHrX;N] 

FNTYPfX] 

FOR (clisp iterative statement operator) 
FOR (in INSERT command) (in editor) ... 

FOR (in USE command) 

FORGET (prog. asst. command) 

fork handle 

f orks 

form-feed 

format and use of history list 

FPLUS[X1;X2;. . . ;Xn] SUBR* 



14.44-51 

14.5- 7 
14.2; 16.8 
18.3 

14.37,44 

14.37.46 

17.17-18 

14.44,49 

14.49 

14.47 

14.44-50; 17.28 

14.44 

14.7 

2.9; 14.1-10 
14.45,48,51 
14.46; 23.60.63 
14.44,49 
23.25-26 
23.25-26 
19.5.7 
14.39 
20.4.9 
21 .24 
13.4 

22.16-17,22 

4.1 
13.4 

17.25-26.28 

2.3; 6,7 

2.3; 6.8 
13.7 

13.6- 7 

3.1,4.6,11; 13.1-2.4. 
10; 14.11 
13.7 

3.6; 14.22 

2.3; 5.14 
13.6 
Al.lO 
15.23 

15.17.22; 19.5 
15.17 

15.17,22; 19.5 

17.27 

14.34 

2.3; 6.8 

4.3; 8.1,3-7 
23.20-21 

9.41 
22. 14 
22.27,54 
21 .20 
21.17 
14.13 
22.44-47 
13.6 
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FQUOTIENT[X;Y] SUBR 

f rce variables 

free variables and compiled functions 

froe-list 

FRr;EVARS[FN;EXPRFLG] 

FRI:MAINDER[X;Y] SUBR 

FROM (clisp iterative statement operator) 

FROM (In event specification) 

FROM (in EXTRACT command) (in editor) .. 

FRPLACAtXjY] SUBR 

FRPLACO[X;Y] SUBR 

(FS ...) (edit command) 

FSTKARG[N;POS] SUBR 

FSTKNTfirN;POS] SUBR 

FSUBR (function type) 

FSUBR* (function type) 

FTIMESCXl;X2;...;Xn] SUBR* 

FUNARG 



FUNARG (function type) 

FUNCTION[EXP;VLIST] NIL 

function definition and evaluation 
function definition cell 



function objects 

function types 

functional arguments 

FUNNYATOMLST (clisp variable/parameter) 

garbage collection 

GC: (typed by system) 

GC: 1 (typed by system) 

GC: 16 (typed by system) 

GC : 18 (typed by system) 

GC: 8 (typed by system) 

GCGAG[MESSAGE] SUBR 

GCiRPI N] SUBR 

flonor.ilized NTH command (in editor) 
GENNUM (system variable/parameter) 
GENSYM[CHAR3 



GET[X;Y] 

GETAB[TABI ENAME; INDEX ;FORMATFLG] 

GETBLKCN] SUBR 

GE IBHKC J SUBR 

GETDtXJ SUBR 

GETIIASUr HEM; ARRAY] SUBR 

GETLIS[X;PROPS] 

GEIPf ATM -.PROP] 

GETvSEPR[ ] SUBR 

GLC[X1 SUBR 

global variables 

GLOBALVARS (compiler variable/parameter) 
GI.OBALVARS (system variable/parameter) 

GNCrX] SUBR 

GOLX] FSUBR* 

GO (break command) 

GO (use In iterative statement in clisp) 
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13.6 

12.2,5 

12.5 

3.12-13 
20.10 
13.6 

23.22-24 
22.13 

9.46 

5.3 

5,3 

9.27 
12.8 
12.7 

4.3; 8.4-6 
4.3; 8.4-6 
13.6 

11.1-2,5-7; 12.11-12, 
16.10; 18.16 
8.5 

M. 1-2, 5, 7; 18.16 
8.1-12 

2.3,6; 3.3; 8.1-2, 
16.1; 18.21 
11.6; 16.1 

4.1-3 

2,3; 8.10; 11.1; 18.16 
23. ,60, 75 

2.4; 3.11-14; 10.13-18 
10.15 

10,13; 16.9 

13.1 

13,1 

10.14; 21.4 

5.10; 10.15 
10.17; 21.4 

9,32,52,60 
10.5 

3.2; 10.4-5; 15.16, 
18.16; 19.4,6 

7,2 
21,22 

16.10; 21.17-18 
14.14 

2.3.6; 8.1-3,7 

7,6; 23.31 

7.3 

7,3 
14.13 
10.7,12 

5,9; 18.6-7 
18.6,29,48,61 
14,27.38 
10.6, 12 

5,7 

15.6-7,15-16; 16.3-4 
23.26 
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GRrATrRPrX;Y] SUBR 13.8 

GRrtT[NAMH;FLG3 22.64 

cjroGtinrj nnd user initialization 22.64 

GROUP (property name) 22.45-46,62 

GTJI N[FILE:;EXT;V;FLAGS3 14.9 

HARRAY[LEN3 7.5 

hash arrays 3.1 

hash link functions 7.5-6 

hash links 7.4-6 

hash overflow 7.7 

HASH TABLE FULL (error message) 7.7; 16.10 

hash-addross 7.4 

hash-array 7.4-5,7 

hash-itom 7.4-6 

hash- link 7.4-6 

hash-value 7.4-6 

HASHRFCORD (record package) 23.53 

MFl PLMLSSl ;MESS2] 16.13 

HELP! (typed by system) 16.13 

HELPCLOCK (system variable/parameter) 16.6; 22.21,38 

HEEPDEPTH (system variable/parameter) 16.5-6 

HELPFLAG (system variable/parameter) 16.3-4,7 

HEIPTIME (system variable/parameter) 16.5-6 

HERE (in edit command) 9.42 

HISTORY (property name) 22.45-46 

history commands 22.10-27 

history commands applied to history commands .... 22.19 

history commands that fail 22.20 

history list 9.73,78; 22.6-14,44 

HISTORYCOMS (editor variable/parameter) 22.61 

HISTORYFIND 22.53 

HISTORYSAVE[ HISTORY; ID ;INPUT1;INPUT2;INPUT3;PR0PS] 22.11,44-46.52.61 

(I c xl ... xn) (edit command) 9,62 

i.s.type 23.20 

I.S.TYPE[NAME;F0RM;1NIT;VAL] 23.28-29 

IDlFFFRENrE[X;Y] 13.3 

(IF X comsl coms2) (edit command) , 9.65 

(IF X comsl) (edit command) 9.65 

(IF x) (edit command) 9.64 

IF-THEN-FESE statements 23.17 

IFPROP (prcttydef command) 14.35-36 

IGREATERPl X;Y] SUBR 13.3 

IE(SSPrX;Y] . 13.4 

ILLEGAL ARG (error message) 6.4; 16.10 

ILLEGAL ARG - PUTD (error message) 8.4; 16.8 

ILLEGAL EXPONENTIATION: (error message) 13.8 

(ILLEGAL GO) (compiler error message) 18.51 

ILLEGAL OR IMPOSSIBLE BLOCK (error message) 16.10; 21.17-18 

ILIEGAL RETURN (error message) 5.7; 16.8 

(ILLEGAL RETURN) (compiler error message) 18.51 

ILIEGAL STACK ARG (error message) 12.6; 16.9 

IMINUS[X] 13.3 

implementation of REDO, USE, and FIX 22.17-19 

implementation of structure modification commands 

(in editor) 9.37-39 

implicit progn 4.4 

IN (clisp iterative statement operator) 23.21-23,27 



INDEX. 13 



Page 
Numbers 



IN (typed by system) 16.4 

IN (in TMBED command) (in «5dltor) 9.48 

IN (in USE command) 2Z.14 

IN? (break command) 15.8,13; 16.1 

INCORRECT DEFINING FORM (error message) 8.7 

incorrect number of arguments 4.3 

indefinite number of arguments 4.2 

INFILE[FILE] SUBR 14.2,6 

INFILEPCFILE] SUBR 14.3-4 

infix operators (in clisp) 23.10-13 

INPUT[FILE] SUBR 5.10; 14.1 

input buffer 10.16; 14.16,20-21, 

23-24; 15.16; 16.2, 

7 

input functions 14.10-18 

input/output 14.1-51 

input/output control functions 14.21-25 

(INSERT ... AFTER . G>) (edit command) 9.41 

(INSERT ... BEFORE . 0) (edit command) 9.41 

(INSERT ... FOR . @) (edit command) 9.41 

INSTRUCTIONS (in compiler) 18.15 

integer arithmetic 13.2-5 

integers 3.4 

interfork communication 21.17 

interpreter 8.9; 16.1 

INTERRUPT[INTFN;INTARGS;INTYPE] 10.17; 16.2 

INTERRUPTED BEFORE (typed by system) 16.2 

INTERSCOPE 20.11-20 

INTERSECT10N[X;Y] 6.9 

I0FILE[FILE] SUBR 14.6-7 

IPLUS[Xl;X2;...;Xn] SUBR* 13.3 

I0U0TIENT[X;Y1 5UPR 13.3 

IRtMAINnERrX;Y] SUBR 13.3 

IS A COMPILED FILE AND CANNOT BE DUMPED, 

(error message) 14.47 

(IS GLOBAL) (compiler error message) 18.51 

IS NOT DEFINED (typed by PRINTSTRUCTURE) 20.5 

ITERATE (use in iterative statement In clisp) ... 23.26 

iterative statements (in clisp) 23.18-30 

ITIMESCXl;X2:...;Xn] SUBR* 13.3 

vlFN , 14.8-10 

0FNS[.1FN;AC3] 14.9 

JOIN (clisp iterative .<»tatement operator) 23.19 

JOINC (edit command) 9.76 

JSYS 14.8-10,22; 21.22 

KFORKCFORK] 21.20-21 

KWOTE[X] 5.3 

L-CASErX;rLG3 ' 9.74; 14.43 

LAMBDA , 4.1-2.4; 8.3,5,8 

LAMBDACOMS (transor command) A1.17 

LAMS (compiler variable/parameter) 18.5,9,11,31-32 

LAP 18.3,34,40 

LAP macros 18.36,43 

LAP op-do^s , 18.35-36 

LAP statements » 18.40-44 

LAPFLG (compiler variable/parameter) 18.3 

LAPRDCFN] 18.25 
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largo integers 



LA5T[X] 

LAST (as argument to advise) 

LAST-PRINTSTRUCTURE 

( printstructure variable/parameter) 
LASTAIL (editor variable/parameter) 

LASTCrFILt:] SUBR 

LASTFNtrN] 

LA5TNrL;N] ' 

LASTPOS (break variable/parameter) .... 

LASTVAIUE (property name) 

I.A5TW0RD (dwlm variable/parameter) .... 
LASTWORO (system variable/parameter) 

(LC . (?) (edit command) 

LCASEFLG (system variable/parameter) 
LCASCLST (prettydef variable/parameter) 
LCFIL (compiler variable/parameter) ... 

(L.CL . (?) (edit command) 

LCONC[PTR;X] 

LDIFFLX;Y;Z] ... 

LOIFF: NOT A TAIL (error message) 

LENGTH[X] 

LE,SSP[X;Y] ^ 

(LI n) (edit command) 

LINBUrfFLG] SUBR . 

lino buffer 

line-buffering 

I ino-f end 

line- food (edita command/parameter) 
LINELENGTH[N] SUBR 



linked function calls 

LINKEDFNS (system variable/parameter) 

LINKFNS (compiler variable/parameter) 

LISP (prog. asst. command) 

LISPFN (property name) 

LISPX[ LISPXX ; LISPXIO ; LISPXXMACROS ; LISPXXUSERFN ; 
LISPXFLG] 



LISPX/[X;FN;VARS] 

LISPXCOMS (prog. asst. variable/parameter) 

LISPXtVALf LISPXFORM;LISPXIO] 

LISPXFINOr HISTORY; LINE ;TYPE;BACKUP;QUIETFLG3 

LISPXIIIST (prog. asst. variable/parameter) 

LISPXIIISTORY (prog. asst. variable/parameter) 

LISPXHISTORY (system variable/parameter) 

LISPXI INE (prog. asst. variable/parameter) 

LISPXMACROS 

LISPXMACROS (prog. asst. variable/parameter) .... 

LISPXPRJNT (property name) 

LISPXPRINT[X;Y;Z;NODOFLG] 

LISPXPRINTFL6 (system variable/parameter) 

LISPXREADCFILE] 



3.1.5,11; 5.12, 
13.1-2,10 

6.7 
19.5.7 

20.6,8-9 

9.16-17,25,84 
14.15 
20.4,9 

6.7 
15.8-10,12 

9.72 

17.13,24-25,27; 23.13 

9.85-86 

9.30 
21.23* 
14.43 
18.3,5 

9.30 

6.3 

6.9 

6.9 

6.8 
13.8 

9.8,53 
14.21 
14 . 21 , 23 

2!5;*14. 11-12, 14-16, 23 

3.2; 14.10,13,18 
21.13 

2.3; 3.8; 5.10; 14.22. 

39 

18.21-26 
18.25 

18.24,29-30 
21.21; 22.34 
23.70 

9.62,73; 22.10-11, 
15-16,19-20,29, 
34-35,37-38,40-41, 
44-49,52,61-62. 

17.5,12-13,28 

22.40,58 

22.38 

22.52 

22.53,62 

22.45-46,56,59-60 

22.44,49,60-61 

22.62 

22.34 

21 .21 

22.34,49 

22.38,45 

22.37,45 

22.38 

22.10,19,29,32,47-48,50, 
61 



INDEX. 15 



Page 
Numbers 



LISPXRHADPN (prog. asst. variable/parameter) .... 14.16; 22.50 

LISPXREADP[FLG] 22.50,61 

LISPXSTAT5[FLG] -22.63-64 

LISPXUNREAD[LST] 22.51 

LISPXliStRPN (prog. asst. variable/parameter) 22.35.37,47,49 

LISPXWATCH[STAT;N] 22.63 

LISTCXl ;X2; . . . ;Xn] SUBR* 3.7; 6.1 

LIST (property name) 8.7 

LIST (makefile option) 14.47 

list manipulation and concatenation 6.1-12 

list nodes 3.8,11 

LISTFILES[FILES] NL« 14.45,47 

LISTING? (compiler question) 18.2-3 

LISTPCX] SUBR 2.3; 5.11 

listp checks (in pattern match compiler) 23.38 

lists 2.3; 3.1,7; 5.11 

LISTS FULL (error message) 16.10 

LITATOM[X] SUBR 5.11 

literal atoms 3.2-3; 6.11; 10.11, 

14.11 

LITS (ndita command/parameter) 21.13 

LLSH[N;M3 SUBR 13.5 

(LO n) (edit command) 9.8,53 

LOAD[FILE;LDFLG;PRINTFLG] 2.9; 14.27,44; 18.8 

LOADAVr ] 21.22 

LOADFNS[FNS;FILE;LDFLG] 14.27-28 

LOCrX] SUBR 13.13-14 

local record declarations (in clisp) 23.35 

local variables 5.6 

LOCALFREEVARS (compiler variable/parameter) 18.19-20,29 

locally bound variables 12.6 

location specification (in editor) 9.28-29,64 

LOCATION UNCERTAIN (typed by editor) 9.17 

LOG[X] 13.8 

LOGANDCXl ;X2; . . . ;Xn] SUBR* 13.5 

L0G0R[X1 ;X2; . . . ;Xn] SUBR* 13.5 

LOGOUT[] SUBR 2.4; 21.4-5,21 

L0GX0R[Xl;X2;...;Xn] SUBR* 13.5 

LOOKATCX] 20.13,17 

LOWER (edit command) 9.74 

lower case 14.43; 21.23 

lower case comments 14.40-43 

(LOWER x) (edit command) 9.75 

LOWERCASEfFLG] 21.23; 23.76 

(LP . corns) (edit command) 9.65-66 

(LPO . corns) (edit command) 9.66 

LRSII[N;M] 13.5 

LSH[N;M] SUBR 13.5 

LSTFIL (compiler variable/parameter) 18.3 

LSUBST[X;Y;Z] 6.5,7 

(M (c) ( nr gl ... argn) . corns) (edit command) ... 9.68 

(M (c) arci . corns) 9.68 

(M c . corns) (edit command) 9.67 

machine Instructions 18.1,40-41; 21.10 

MACRO (property name) 18.13-14 

macros (in editor) ,. 9.67-70 

macros (in compiler) 18.14-16 
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MAKEBITTABLE[L;NEG;A3 10.10 

MAKEFILE[f ILE;0PTI0NS3 14.45-48; 16.10,32, 

17.28 

makefile and clisp 23.33,75 

MAKEFU rSf OPTIONS ;FILES] 14.45,47-48,51 

MAKESYSrFILE] EXPR 3.15 

MAkESYSDATE (system variable/parameter) 3.15 

NAKEUSERNAMES 22.65 

MAPrMAPX;MAPFNl ;MAPrN2] 11.2 

MAP2CrMAPX;MAPY;MAPFNl;MAPFN2] 11.4 

MAP2CARrMAPX;MAPY;MAPFNl;MAPFN2] 11.4 

MAPATOMS[FN] SUBR 10.5 

MAPC[MAPX;MAPFN1 ;MAPFN2 3 11.3 

NAPCARrMAPX;MAPFNl ;MAPFN2] 11.3 

MAPCONI MAPX ;MAPFN1 ;MAPFN2 ] 11.3 

MAPCONCrMAPX;MAPFNl ;MAPFN23 11.3 

MAPDLl MAPnLFN;MAPDLPOS] 12.11 

NAPIIASni ARRAY;MAPHFN] 7.6 

MAPLISTrMAPX;MAPFNl;MAPFN2] 11.3 

MAPR1NT(;LST;FILE;LEFT;RIGHT;SEP;PFN;LSPXPRNTFLG].. 11.5 

mcirtjlns (for prettyprint) 14.38 

MARK (edit command) 9.34 

(NARK atom) (edit command) 9.34 

MARKI.ST (editor variable/parameter) 9.34,84 

MASK (cdita command/paramotGr ) 21.15 

MATCH (use in pattern match In clisp) 23.37 

MAXLEVEL (editor variable/parameter) 9.24,28 

MAXLOOP (editor variable/parameter) 9.66 

MAXLOOP EXCEEDED (typed by editor) 9,66 

(MBD el ... em) (edit command) 9.47 

MEMBrX;Y] 5.14 

MEMBER[X;Y] ' 5.14 

Ml RGEf A;B ;COMPAREFN] 6.11 

MINrS[N;TYP] SUBR 3.13-14; 10.16 

MINIIS[X1 SUBR 13.7 

MINUSP[X] SUBR 13.4.6 

MISSING OPERAND (dwim error message) 23.64 

MISSING OPERATOR (dwim error message) 23.64 

MISSPEl I E0?[XWORD;REL;SPLST;FLG;TAIL;FN] 17.24,27-28 

mixed arithmetic 13.7-8 

MKATOMtXJ SUBR 3.2,5-6; 10.7 

NKSTRINGCX] SUBR 3.10-11; 10.5,11 

NOnEL33rLG (dwim variable/parameter) 17.21; 23.76 

MODEL33rLG (system variable/parameter) 21.23 

MOV/n[rROM;TO;COPYFLG] 8.4 

(MOVE 01 TO com . 02) (edit command) 9.48 

(MULTIPLY DEFINED TAG) (compiler error message) . 18.50 
(MULTIPLY DEFINED TAG, ASSEMBLE) 

(compiler error message) 18.50 

(MULTIPLY DEFINED TAG, LAP) 

(compiler error message) 18.50 

n (n n number, edit command) 9.3,17 

(N el ... em) (edit command) 9.36 

(n el ... cm) (n a number, edit command) 9.5,36 

(n) (n a number, edit command) 9.5,36 

NAME (prog. asst. command) 22.14,22,25-26 

NAMES RESTORED (typed by system) 15.24 
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NAMESCHANGEO (property name) 15.17 

NARGS[X] 8.1,3-4,6 

NCHARS[X] SUBR 10.3; 14.6 

NCONCCXl ;X2; . . . ;Xn] SUBR* 6.2-3 

NC0NC1CLST;X3 6.2-3 

NEQ[X;Y3 5.12 

NEVER (clisp Iterative statement operator) 23.20 

NEW/FNCFN] 22.57 

NEWFILE2[NAME;C0MS;TYPE;UPDATEFLG] 14.49-50 

NCWFILE?[NAME;VARSFLG3 9.86 

NEX (edit command) 9.32 

(NEX x) (edit command) 9.32 

NIL (edit command) 9.64,70 

NIL (use in block declarations) 18.30 

NIL: 20.6 

NLAM (transor command) A1.15 

NLAMA (compiler variable/parameter) 18.5,9,11,31-32 

NLAMBDA 4.1-2.4; 8.3,5 

NLAML (compiler variable/parameter) 18.5,9,11,31-32 

NLEFT[L ;N;TAIL3 6.7 

NLISTP[X] 2.2; 5.11 

NLISTPCOMS (transor command) A1.16 

NLSET0CNLSETX3 NL 5.8; 16.14; 18.16, 

, . . , , 22 .59 

(NO LONGER INTERPRETED AS FUNCTIONAL ARGU^^ 

(compiler error message) 18.49 

NO VALUE SAVED: (error message) 22.56 

NOBIND 2.3,8; 3.3; 5.9; 9.86, 

14.27; 16.1; 22.43,55 

NOBREAKS (break variable/parameter) 15.20 

NOCLISP (makefile option) 14.46; 23.33,75 

NOnxiNSLST (clisp variable/parameter) 23.62-63,72 

NOFIXVARSIST (clisp variable/parameter) 23.62-63,65,72 

NOFNS (printstructure variable/parameter) 20.3 

NOLINKFNS (compiler variable/parameter) 18.24-25,29-30 

(NON ATOMIC CAR OF FORM) (compiler error message). 18.49 

NON-NUMERIC ARG (error message) 13.2,6-7; 16.4,8 

NONXMEM (error message) 16.7 

NOSAVE 22.56-57 

NOSPELLFLG (clisp variable/parameter) 23.72 

nospread functions 4.2; 8.1 

NOSUBSTfNS (prog. asst. variable/parameter) 22.58 

N01[X] SURR 5.12 

NOT A FUNCTION (error message) 8.8; 19.6 

NOT BLOCKED (typed by editor) 9.79 

(NOT BROKLN) 15.22 

NOT CIIANGfO. SO NOT UNSAVED (typed by editor) ... 9.85 

NOT COMPILEABLE (compiler error message) 18.51 

(NOT COMPILEABLE) (compiler error message) 18.7,51 

(NOT DEFINED WHEN LINK TRIED FROM) 

(typnd by system) 18.24 

NOT EDITABLE (error message) 9.83,85 

NOT FOUND (compiler error message) 18.12,52 

(NOT FOUND) (typed by break) 15.9 

(NOT FOUND) (typed by breakin) 15.20-21 

(NOT FOUND) (value of unsavedef) 8.8 

(NOT IN FILE ~ USING DEFINITION IN CORE) 

(compiler error message) 18.52 
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NOT ON BLKFNS (compiler error message) 

(NOT PRIN TABLE) 

NOIANYrSOMtX;SOMErNl ;S0MEFN2] 

NOTCOMPILI OFILES (file package variable/parameter) 

NOTE (transor commancl) 

NOTE: (JRKEXP NOT CHANGED, (typed by break) 

NOTEVERY[f VERYX;EVERYFN1 ;EVERYFN2] 

(NOTHING FOUND) 

NOTHING SAVED (typed by editor) 

NOTHING SAVED (typed by system) 

NOILISTEDFILES (file package variable/parameter).. 
NOTRACEFNS ( prlntstructure var-iable/pararaeter ) 

NP (in nn assemble statement) 

NTH[X;N] 

(NTH n) (n a number, edit command) 

(NTH x) (edit command) 

NTHCHAR[X;N] SUBR 

NTYP[X3 SUBR 

NULL[X] SUBR 

null string 

null-check 

number stack 

NUMBERPCX] SUBR 

numbers 



NX (edit command) 

(NX n) (n a number, edit command) 
OCCURRENCES (typed by editor) .. 

octal 

OK (break command) 



OK (edit command) 

OK (odita command/parameter) 

OK TO REEVALUATE (typed by dwim) 

OKREEVALST (dwim variable/parameter) 

OLD (clisp iterative statement operator) 

ON (clisp iterative statement operator) 

OPCODE (in a lap statement) 

(OPCODE? - ASSEMBLE) (compiler error message) ... 
OPD (property name) 



open functions 

open macros 

OPFNFLFILE;X] SUBR 

opening files 

OPFNP[ FILE; TYPE] SUBR 

0PFNR(A1 .SUBR 

OPNJFN[FILE] SUBR 

ORf XI ;X2; . . . ;Xn] FSUBR* 

order of precedence of CLISP operators 

(ORF ...) (edit command) 

ORG (edita command/parameter) 

(ORR ,..) (edit command) 

OUT FILE[ FILE] SUBR 

OUTFILEP[FILE] SUBR 

OUTPUT[FILE] SUBR 

output buffer 



18.20,27.52 
14.30 

5.14 
14.45-46,48 
Al.12.14 
15.12 

5.14 

8.8 

9.78 
22.22,39 
14.45-48 
20.4 
18.46 

6.8 

9.20 

9.32-33 
10.3 
10.14 

5.12 
10.6-7 

2.2; 6.7-9 
12.2; 18.46 

5.11 

5.11; 13.1-14, 
14.11-12 
9.8, 18-19 
9.19 
9.65 

3.5,8; 13.13; 14.11.18 
15.6-7,12,14,16. 
16.3-4 

9.71,76.83 
21.13 
17.9 
17.9 

23.8,21-22 

23.21,23 

18.41 

18.35,51 

18.35-36,41,43, 

21.10-11 

18.13-14 

18.15 

14.8 

14.1 . 

14.3-5,8 

10.18 

14.8 

5.13 
23.15 

9.27 
21.12 

9.66 
14.2,6-7 
14.3-4 

5.10; 14.1 
14.20 



INDEX. 19 



Page 
Numbers 



OUTPUT FILE: (compiler question) 18.2,5 

output functions 14.18-20 

overflow 13.3»6 

P (edit command) 9.2,60 

P (prettyiief command) 14.34 

(P m n) (edit command) 9.60 

(P m) (edit command) 9.60 

P-STACK OVERFLOW (error message) 16.7 

P.P.E. (typed by PRINTSTRUCTURE) 20.5,8 

PACK[X] SUBR 3.2,5-6,11; 10.2 

PACKC[X] SUBR 10.4 

paqe 3.11 

PAGEFAULTS[] 21.4 

pnr«imetor pushdown list 12.2,8-9,11; 18.46 

parentheses counting (by RliAD) 14.11,23-24 

PARENTHESIS ERROR (error message) 5.3 

PATHS[X;Y;TYPE ;MUST; AVOID ;ONLY] 20.14-15 

PATLISTPCHECK (in pattern match compiler) 23.38 

(pattern .. 0) (edit command) 9.33 

pattern match (in editor) , 9.21-23,88-89 

pattern match compiler 23.36-48 

PATVARDEFAULT (in pattern match compiler) 23.39,42,45 

PD (prettydef command) 14.35 

PEEKCCFILE] SUBR .... 14.15,25 

place-markers (in pattern match compiler) 23.44 

PLUS[X1 ;X2; . . . ;Xn] SUBR* 13.7 

pname cell 3.3 

pnames 3.1-4,11; 10.1-4,11 

pointer 3.1 

POSITIONCriLE] SUBR „ 14.23 

PP[X] ML* 14.29: 18.46 

PP (edit command) 9.2,60 

PP*[X] NL« 14.31 

PP* (edit command) 9.61 

PPT (edit command) 9.61; 23.31,75 

PPV (edit command) 9.61; 14.38 

PRDEPTH (printstructure variable/parameter) 20.4 

precedence rules (for CLISP operators) 23.10 

predicates , 2.3; 5.11 

prefix operators (in clisp) 23.13 

PRESCAN[FTLE;CHARLST1 A1.3 

PRETTYCOMSPLST (prettydef variable/parameter) ... 14.36 
PRETTYDEF[ PRETTYFNS ; PRETTYFILE ; PRETTYCOMS; 

RECOMPILEFLG;CHANGES] 2.9; 5.9; 14.31-38,40, 

44,46; 19.9 

prettydef commands 14.33-37 

PRETTYFLG (prettydef variable/parameter) 14.39-40,46 

PRETTYLCOM (prettydef variable/parameter) 14.39 

PRETTYMACROS (prettydef variable/parameter) 14.36,40,49-50 

PRETTYPRINT[FNS;PRETTYDEFLG] 2.9; 14.29 

PRFTTYTRANFLG (clisD variable/parameter) 14.46; 23.31-32,75 

PRETTYTYPE (property name) 14.50 

PRETTYTYPELST (file package variable/parameter) . 14.45,50 

primary input file 14.1-2,4,10 

primary output file 14.1,4,18 

PRIN1[X;FILE] SUBR 3.2,8,10; 14.18-19 

PRIN2[X;FILE] SUBR 3.2.8.10; 14.18-19 
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prinZ-pnames 10.1,3-4 

PRIN3[X;F1LE] SUBR 14.19 

PRINTr.X;FILE] SUBR 3.2,8.10; 14.19 

PRINT (property name) 22.45 

print namo 10.1 

PRIN7nAU:rFILE ;CHANGES] 14.29,37,44,46 

PRINTDEI rLXPR;LEFT;DEF] 14.38-39 

PRINTFNStX] 14. a? 

PRINTHISIORYC HISTORY; LINE ;SKIPFN:N0VALUES3 22.22,37-38.60 

printing circular lists 21.24-29 

printlovel 14.19-20 

PRINTLEVEUN] SUBR 2.3; 3.8; 5.10; 14.19 

PRINTSIRUCTURECX;EXPRFLG;FILE] 20.1-10 

private pages 3.15 

PR0G[ARGS;El;E2;.,.;En] FSUBR* 5.6 

PROG label 5.7 

PROGUXl ;X2; . . . ;Xn] SUBR 5.6 

PROGN[ XI ;X2;...;Xn] FSUBR* 4.4; 5.6 

pronrammer's assistant 22.1-48 

programmer's assistant and the editor 22.61 

programmer's assistant commands 22.10-31 

prompt character 2.4,6,8; 9.2; 16.4, 

22.10,33,51 

PROMPT#FLG (prog. asst. variable/parameter) 22.33,51 

PROMPTCHAR[ID;FLG;HIST] 22.33,51,61 

PROP[X;Y] 8.7 

PROP (prettydef command) 14.33,36 

PROP (typed by editor) 9.85 

proper tail 5.15 

property 7.1 

property list 2.3; 3.3; 7.1-3; 16.1 

property name 7.1,3 

property value 7.1,3 

PROPRECORD (record package) 23.53 

PSTCP (in an assemble statement) 18.46 

PSIEPN (in an assemble statement) 18.46 

pushdown list 2.8; 4.2; 12.1-13 

pushdown list functions 12.6-lt 

PUT[ATM;PROP;VAL] 7.1-2 

PU1D[X;Y] SUBR 2.3.6; 8.1-4 

PUTDQ[X;Y] NIL 8.4 

PUTMASm; ITEM ;VAL; ARRAY] SUBR 7.5 

0 (following a number) 3.5; 13.13; 14.11,16, 

22 

QUIT (tcnex command) 14.48; 21.18-19,21 

QUOTE[X] NL« 5.3 

OUOTEFNS (printstructure variable/paramoter) .... 20.4 

QUOTICNTCX;Y] SUBR 13.7 

R (edit command) • 6.6 

(R X y) (odit command) 9.7,57 

(Rl X y) (edit command) 9.59 

RADIXLN] SUBR ..... 2.3; 3.5; 5.10; 10.1, 

14.11,18.22 

RAISELFLG] EXPR 21.22 

RAISE (odit command) 9.74 

(RAISE X) (edit command) 9.75 

RAISEFLG (system variable/parameter) 21.23 
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RANDC LOWER ;UPPER] 13.9 

random numbers 13.9 

RANDSETCX] 13.10 

RANDSTATE 13.9-10 

RATEST[X] SUBR 14.14 

RATOM[FILE] SUBR 14.11-13,25 

RATOMSCA;rN] 14.12 

RC (makefile option) 14.46 

(RC X y) (edit command) 9.59 

(RCl X y) (edit command) 9.59 

READ[FILE;FLG] SUBR 14.10-11,24 

READBUF (prog. asst. variable/parameter) 22.50-51 

READC[FILE] SUBR 14.14,25 

READFILE[FILE] 14.28 

REAOLINE[LINE;LISPXFLG] 9.81; 14.16-17; 22.14, 

19,32.37,47-48,50,61 

READP[FILE] SUBR 14.16 

READVICE (property name) 19.8-10 

READVISE[X] NL* 14.34; 19.8-9 

REBREAKCX] NL* 15.16,22-23 

RECLAIMfN] SUBR 3.12-13; 10.14 

RECOMPILE[PFILE;CFILE;FNS;C0REFL6] 14.44.46.48; 18.7-8,10, 

30,33 

reconstruction (in pattern match compiler) 23.46 

RECORD (record package) 23.52 

record declarations (in clisp) 23.35,51 

record package (in clisp) 23.48-58 

RECORDS (prettydef macro) 23.50-51 

REDEFINE? (compiler question) 18.4 

RLDEFINED (typed by system) 8.7 

(REDEFINED) (typed by system) 14.27 

REDO (prog. asst. command) 22.14,17.22 

REENTER (tenex command) 2.4,9; 5.10; 21.4,19 

REHASH[01DAR;NEWAR] SUBR 7.6 

RELBLK[ADDRESS;N] SUBR 16.10; 21.18 

RELINkrrN;UNLINKFLG] 18.25-26 

relinking 18.25-26 

relocation information (in arrays) 3.8 

RENAINDERtX;Y] SUBR 13.7 

REMARK (transor command) A1.12 

REM0VE[X;L] 6.4 

REMPROPrATM;PROP] 7.2 

REPACK (edit command) 9.75 

(REPACK (3) (edit command) 9.76 

REPLACE (use in records in clisp) 23.57 

(REPLACE (3 WITH ...) (edit command) 9.42 

replacements (in pattern match compiler) 23.45 

REREADFLG (prog. asst. variable/parameter) 22.50,52 

RESETt] SUBR 16.13; 22.43,55 

RESETFORM[RESETX;RESETY;RESETZ] NL 5.10 

RESETVAR[RESETX;RESETY;RESETZ] NL 5.9; 9.77; 18.7 

(RESETVAR var form . corns) (edit command) ....... 9.77 

restoring input buffers 22.30 

RESULTSC] 21.5,7 

RETEVAL[POS;FORM] SUBR 12.10; 15.5; 17.15 

RETFNS (compiler variable/parameter) 18.20,26,29 

RE TFROM[POS; VALUE] SUBR 12.10; 15.5; 16.6 
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retrieve: (prog. asst. command) 'ZZ.ZZ,ZQt3^ 

RETRY (prog. asst. command) 22.21-22 

RETURN[X] SUBR 5.7 

RETURN (break command) 2.9; 15.6-7,16; 16 

4 

RETURN (use in iterative statement in clisp) .... 23.26 

REUSING (record package) 23.56 

REVERSEtL] 6.4 

(Rl n m) (edit command) 9.8,53 

RLJFNCJFNJ 14.9 

(RO n) (edit command) 9.8,53 

RPAQf.RPAOX;RPAQY] NL 5.9; 14.27.32; 22. 

RPAQQ[X;Y] NIL 5.9; 14.27,32-33, 

, 22 .43 

RPLACA[X;Y] SUBR .*..'..!...*..! 5^3 

RPl ACDrX;Y] SUBR 5.2 

RPLSTRING[X;N;Y] SUBR 10.7.12; 16.10 

RPT[RPTN;RPTF] 8.10-11 

RPTO[RPTN;RPTF] NL 8.11 

RSM[N;M] 13.5 

RSTRING[ ] SUBR 10.5; 14.12 

rubout 2.5; 14.23; A3.1 

RUN (tencx command) 3.15 

run-on spelling corrections 17.5,25-27 

running other subsystems from within INTERLISP .. 21.18 

S (response to compiler question) 18.4 

(S var . (?) (edit command) 9.36 

SASSOC[XSAS;YSAS] 5.15 

SAVE (edit command) 9.72,74,83-84 

SAVE EXPRS? (compiler question) 18.4 

SAVEDEf-rXl 8.7-8 

SAVESEir NAME; VALUE ;TOPFLG;FLG] 22.40,43,55 

search alriorithm (in editor) 9.23-25 

searching files .". 14.7 

searching strings 10.8-10 

soarchino the pushdown list 12.6,9 

SEARCHING... (typed by breakin) 15.21 

SEARCIIPDLrSRCIIFN;SRCMPOS] 12,11 

second pass (of the compiler) 18.34 

sogmont patterns (in pattern match compiler) .... 23.41-43 

SELECT0[X:Yl;Y2;...;Yn;Z] NL« 5.4-5 

separator characters 14.12-15,19,24 

SET[X;Y1 SUBR 5.8 

SETArA;N;V] 3.8; 10.13; 16.10 

5ETARG[VAR;M;X] FSUBR 8.12 

SEIBRK[LST;FLG] SUBR 14.12-13,15,19 

SETr)[A;N;V] 3.8; 10.14 

SETf N (property name) 23.70 

SETN[VAR;X] NL 13.10-12 

SE10i:X;Y] FSUBR* . . 5.8 

SETQ (in an assemble statement) 18.38 

SETQOI XSET;YSET] NL 5.8 

SETSEPRILST;FLG] SUBR 14.12-13,15.19 

SFPTR[FILE;ADDRESS] SUBR 14.6-7.23; 16.10 

SHALL I LOAD (typed by dwim) 17.17 

shared pages 3.15 

shared system 3.15 
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sharing 3.15 

SHOW (transorset command) ALIO 

(SHOW . X) (edit command) 9.66 

SIDE (property name) 22.45-46,56-67,59,61 

SIN[X;RADIANSFLG] 13.9 

skip-blip 12.11 

SKOR 17.21-22 

SKREAD[FILE;REREADSTRIN6] 14.17-18.28 

slot (on pushdown list) 12.2,6,8,10 

small integers 3.1,5; 5.12; 13.1-2 

SMALLP[N] 3.5; 13.2,4 

SNOMSG (prog. asst. command) 21.21; 22.34 

S0ME[S0MEX;S0MEFN1;S0MEFN2] 5.13 

S0RT[DATA;C0MPAREFN] 6.10 

SP (in an assemble statement) 18.38,46 

space 3.2; 14.13 

SPACES[N;FILE] SUBR 14.19 

SPfCVARS (compiler variable/parameter) 18.18,26,29 

spelling completion 17.11 

spelling correction 9.82,86 

spelling correction protocol 17.5-7 

spelling corrector 17.2,10,20,26 

spelling lists . 17.11-14 

SPELLINGSl (dwim variable/parameter) 17.12-14,18,24 

SPELL1NGS2 (dwim variable/parameter) 17.12-14,18,23-24 

SPELLINGS3 (dwim variable/parameter) 22.55; 17.12,14,16,24 

(SPLITC x) (edit command) 9.77 

spread functions 4.2; 8.1 

spreading arguments . .' 4.2 

SQRTCNJ 13.8 

SORT OF NtGATIVE VALUE (error message) 13.8 

square brackets 2.5 

square brackets (inserted by prettyprint) 14.38 

SRCCOM 6.12 

ST (response to compiler question) 18.2,4 

stack position 12.6-7,9-10 

statistics 22.63 

STKARG[N;POS] SUBR 12.8-9; 15.9 

STKARGSCPOS] 12.9 

STKEVAL[POS;FORM] SUBR 12.10-11; 15.9 

STKNAMEfPOS] SUBR 12.7 

STKNARGSCPOS] SUBR 12.8 

STKNTH[N;POS] SUBR ., 12.7-9 

STKPOS[rN;N:POS] 12.6-7,9 

STKSCAN[VAR;POS] SUBR 12.10 

STOP (edit command) 9.71-72,76,83-85, 



15.20 

14.27-29,38 
10.16 
3.11 
10.5 

18.3-4,8 

3.1.10-11; 10.11 
10.5-10 

3.1,10-11; 10.6,11 
10.11-12 

5.11; 10.5 



STOP (at the end of a file)) 

ST0RAGE[FLG3 

storage allocation 

STREOUAi.[X;Y] 

STRF (compiler variable/parameter) 

string characters 

string functions 

string pointers 

string storage 

STRINGPtX] SUBR 
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strings 3.10; 5.11; 14.11 

STRPOS[X;Y;START;SKIP;ANCHOR;TAIL] 10.8-9; 14.7 

vSTRPOSL[A;STR;START;NEG] 10.9-10 

structure modification commands (in editor) 9.36-60 

surn[X] 13.3 

SUBLISf ALST;EXPR;FLG] 6.6-7 

SUBPAIR[OLD;NEW;EXPR;FLG] 6.6-7 

SDBR (function type) 4.3; 8.4-8 

SUim* (function type) 4.3; 8.4-6 

SUBRPrFN] SUBR 8.1,3-5 

subrs 8.1 

SlJBSfIT[MAPX;MAPFNl;MAPFN2] 11.4 

SUBST[X;Y;Z] 6.5,7 

substitution macros 18.16 

SUBSTRING[X;N;M] SUBR 3.10; 10.6,11 

SUBSYS[ F II E/FORK ; INCOMFILE jOUTCOMFILE ; 

ENTRYPOINTFLG] 14.48; 21.18-21; 22.34 

SUN (clisp iterative statement operator) ........ 23.19 

(SURROUND Q IN ...) (edit command) 9.48 

SVFLG (compiler variable/parameter) 18.3-4 

(SW n m) (edit command) 9.59-60 

SY (prog. asst. command) 22.34 

symbolic file input 14.27-28 

symbolic file output 14.29-38 

SYMIST (erlita command/parameter) 21.14 

SYSBUFCFLG] SUBR 14.21 

SYSFILFS (system variable/parameter) 14.49 

SYSHASflARRAY (system variable/parameter) 7.5,7 

SYS INf FILE] SUBR 2.9; 14.26; 16.9 

SYSLINKEOFNS (system variable/parameter) 18.26 

SYSOUTLFILE] EXPR 2.9; 14.21,26 

SYSOUTGAG (system variable/parameter) 22.65 

SYSPR0P5 (prcttydef variable/parameter) 14.33 

SYSPROPS (system variable/parameter) 7.3 

SYSTAT 21.24 

T FIXED (typed by dwim) 17.8 

tab 14.13 

TAB[POS;MINSPACES;FILE] 14.37 

tab (cdita command/parameter) 21.12 

tail of a list 5.15 

TAILP[X;Y] 5.15 

TANrX;RADIANSFLG] 13.9 

TCOMPLCFILES] 14.44,46; 18.7-10,30-31 

TCONC[PTR;X] 6.2-3 

TECO (prog. asst. command) 21.21; 22.34 

teletype 9.61; 14.1.4,10-11.16, 

20,23.31 

teletype initiated breaks 16.2-3 

TENEXLSTR] 21.24 

TENEX 2.4,6,9; 3.2,6,15, 

13.13; 14.2-4.6-8,40. 

21.2,4.18-19,21-22, 

23.76; 20.6 

TERPRI[FILE] SUBR 14.19 

TEST (edit command) 9.79 

TEST (transorset command) Al.ll 

TESTMODE[FLG] 22.41 
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TESTMODEFLG (prog. asst. varlable/parametGr ) .... 22.41 

THIREIS (clisp iterative statement operator) .... 23.20 

THRU (edit command) 9.64-57 

THRU (in event specification) 22.13 

TIML[TIMtX;TIMEN;TIMETYP] NL 21.1-2 

time-slice (of history list) , 22.8,54 

TIMES[X1 ;X2; . . . ;Xn] SUBR* 13.7 

TO (clisp iterative statement operator) 23.22,24 

TO (edit command) 9.54-57 

TO (in event specification) 22.13 

too few arguments 4.3 

too many arguments 4.3 

TOO MANY FILES OPEN (error message) 16.8 

TOP (as argument to advise) 19.5,7 

top level value 5.1,3,9 

TRACE[X] NIL* 15.1,7,14,18-19,21 

translation notes A1.4 

translations (in clisp) 23.30-33 

TRANS0R[50URCEFILE] Al.3-4 

TRANSOR Al.1-17 

transor sweep A1.14 

TRANSORFNS A1.4 

TRANSORFORM A1.4 

TRANSORSETC] Al.2,8 

TRAPCOUNTCX] SUBR 18.19 

TREAT AS CLISP ? (typed by dwim) 23.66 

TREATASCLISPFLG (clisp variable/parameter) 23.66 

TREELST ( printstructure variable/parameter) 20,8 

TREEPATHS[X;Y;TYPE;MUST;AV0ID;0NLY3 20.16 

TREEPRINT[X:N] 20.9 

true 2.2; 5.4 

TRUSTING (DWIM mode) 17.3,5,23; 23.5,66-67 

TTY: (edit command) 9.66.70-72; 15.19-20 

TTY: (typed by editor) 9.71 

type numbers 10.14 

TYPE-AHEAD (prog. asst. command) 22.28-29 

TYPEP[X;N1 10.15 

TYPERECORD (record package) 23.52 

U (value of ARGLIST) 8.6 

(U V W) (value of ARGLIST) 2.3; 8.6 

U-CASE[X] 9.74; 14.43 

U.B.A. (error message) 2.8; 16.1,4; 17.15 

U.B.A. breaks 15.10 

U.D.F. (error message) 16.1-2,4; 17.2,15 

U.O.F. breaks 15.11 

U.D.F. T (typed by dwim) 17.8 

U.D.F. T FIX? (typed by dwim) 17.8 

UB (break command) 15.8 

UCASELST (prettydcf variable/parameter) 14.43 

UNADVISEtX] NL* 19.6,8-9 

UNADVISED (typed by system) 15.24 

UNARYOP (property name) 23.69 

UNBLOCK (edit command) 9.79 

unbound atom 16.1; 17.14-18 

unboxed numbers 13.13 

unboxed numbers (in arrays) 3.8; 10.12 

unboxing 13.1-2,12 
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UNBRtlAKCX'l NL* 15.17.21-22; 21.6 

UNBREAKO[FN;TAIL] 15.22 

(UNBRbAKABLE) 15.21 

UNBREAKIN[FN] 15.22 

UNBROKEN (typed by system) 15.24 

UNBROKEN (typed by advise) 19.6 

UNBROKEN (typed by compiler) 18.7 

uridofinod function 16.1; 17.14-18 

UNDEFINED OR ILLEGAL GO (error message) 5.7; 16.8 

(UNDEFINED TAG) (compiler error message) 18.50 

(UNDEFINED TAG) (error message) 5.7 

(UNDEFINED TAG. ASSEMBLE) (compiler error message) 18.50 

(UNDEFINED TAG, LAP) (compiler error message) ... 18.50 

UNDO (edit command) < 9.10,78; 22.61 

UNDO (prog. asst. command) 22.13,22-23,43,58,61, 

17.4 

undoing 22.5,38,55,62 

undoing (in editor) 9. 10,36, 78-79; 22.62 

undoing DWIM corrections 22.23; 23.63 

undoing out of order 22.23,42 

UN0OLISPX[ LINE] 22.58 

UNDOLISPXi[EVENT;FLG;DWIMCHANGES] 22.59 

UNDOLST (editor variable/parameter) 9.72.78-79.84; 22.62 

UNDONE (typed by editor) 9.78 

UNDONE (typed by system) 22.22,59 

UNDONLSETOIUNDOFORM;UNDOFN] ML 22.59 

UNDOSAVE[UNDOFORM;HISTENTRY] 22.45-46.56 

UNFIND (editor variable/parameter) 9.25,35,41-42,46.48-51. 

72-73.76,84 

UNION[X;Y] 6.9 

UNLESS (clisp iterative statement operator) 23.22 

UNPACK[X;FLG] SUBR 10.2-3 

unroading 22.10-11.18.51 

UNSAVED (typed by dwim) 17.17-18 

UNSAVED (typed by editor) 9.85 

UNSAVEDLFrX;TYP] 8.8; 17.17-18 

UNSETfNAMr] 22.43.56 

UNTIL (clisp iterative statement operator) 23.22 

UNUSUAL CDR ARG LIST (error message) 16.9 

UP (edit command) 9.12,15-16,25,43 

UPOATLFILLSC ] 14.45,50-51 

UPFINDFIG (editor variable/parameter) 9.25,28,44 

URFAD[FILE;FLG] SUBR 14.11-12,15,24 

USE (prog. asst. command) 22.14-15,17.22 

USE -ARCS (property n<ime) 22.45 

(USED AS ARG TO NUMBER FN?) 

(compiler error message) 18.51 

(USED BLKAPPLY WHEN NOT APPLICABLE) 

(compiler error message) 18.51 

USFREXLCf L1SPXID;LISPXXMACR0S;LISPXXUSERFN] 22.49 

USERNACROS (editor variable/parameter) 9.70; 14.35 

USLRNACROS (prettydef command) 9.70,80; 14.35 

USLRNAME[A] 21.23 

USf RNAME (prog. asst. variable/parameter) 22.65 

USERNAME (system variable/parameter) 21.24 

USERNAMELST (prog. asst. variable/parameter) 22.65-66 

USERNUMBER[A] 21.23 
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USFRSYMS (edita commnnd/parameter ) 21.14 

USERWORDS (dwim variable/parameter) 17.13-14,23,27-28 

USFRWORDS (system variable/parameter) 9.85-87 

USING (record package) 23.56 

VAG[X] SUBR 13,13-14 

VALUE (property name) 5.9; 22.43,55-56 

value coll 2.3; 5.1,9; 12.1, 

16.1 

value of a break 15.6; 16.2 

value of a property 7.1 

VALUEOF[X] NIL* 21.20; 22.33,46,54 

variable bindings 2.8; 11.5-7; 12.1-6 

VARIABLESf POS] 12.9; 15.10 

VARPRIN1[D0NELST;TREELST3 20.9 

VARS[rN;EXPRFLG] 20.10 

VARS (prettydef command) 14.34 

version numbers 14.2 

VIRGINFN[rN;FLG] 15.23 

WHEN (clisp iterative statement operator) 23.22 

WHERE (clisp Iterative statement operator) 23.29 

WIIEREIS[X] 14.48 

WHILE (clisp iterative statement operator) 23.22 

WIDEPAPER[FLG] 14.39 

WITH (in REPLACE command) (in editor) 9.42 

WITH (in SURROUND command) (in editor) 9.48 

WORLD (as argument to RELINK) 18.25 

WRITEFILE[X;FILE;DAIEFLG] 14.29 

(XTR , 0) (edit command) 9.45 

YESFNS ( printstructure variable/parameter) 20.3 

ZEROP[X] 13.4 

0 (edit command) 9.4-5,17 

^ (carriage-return) 2.5 

~ (in pattern match compiler) 23.40 

- (clisp operator) 23.14 

! (in pattern match compiler) , 23.41-43 

! (use with <,> in clisp) 23.16 

M (use with <,> in clisp) 23.16 

!0 (edit command) 9.18 

!E (proQ. asst. command) 22.31 

!E (edit command) 22.31,61 

!EVAL (break command) 15.7 

!F (prog. asst. command) 22.31 

!F (edit command) 22.31,61 

!G0 (break command) 15.7,16 

!N (prog. asst. command) 22.31 

!N (edit command) 22.31,61 

!NX (edit command) 9.19-20 

!0K (break command) 15.7,16 

•UNDO (edit command) 9.78 

! VALUE (break variable/parameter) 15.7,16 

!VALUE (with advising) 19.2,4 

" 3.2,10; 14.11-14,19 

# (followed by a number) 3.8; 10.13; 13.13, 

14.19 

##[COMS] NL« 9.29,63 

## (typed by system) 2.4; 14.10,23,25 



## (In INSERT, REPLACE, and CHANGE commands) 9.43 
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#0 12.4-5 

^0 (use in history commands) 22.18,50-51 

#n (n a number, in pattern match compiler) 23.44 

#RPARS (prettydcf variable/parameter) 14.38 

#SPELLINGS1 (dwlm variable/parameter) 17.14 

#SPELLINGS2 (dwim variable/parameter) 17.14 

#SPELLINGS3 (dwim variable/parameter) 17.14 

#UNOOSAVIES (prog. asst. variable/parameter) 22.39,56-57,60 

#USERWORDS (dwim variable/parameter) 17.14 

$ (alt-mode) 14.2 

$ (alt-mode) (in edit pattern) 9.12,21 

$ (alt-mode) (prog. asst. command) 22.23-25 

$ (alt-mode) (in clisp) 23.13-14 

$ (alt-mode) (in spoiling correction) 17.11,25 

5 (alt-mode, in R command) (in editor) 9.58 

$ (dollar) (edita command/parameter) 21.13 

$ (dollar) (in pattern match compiler) 23.41 

$$ (two alt-modes) (in edit pattern) 9.22 

SSVAL (use in iterative statement in clisp) 23.28 

$1 (in |)attern match compiler) 23.39 

Slims (alt-modcBUFS) (prog. asst. command) 9.7; 22.30; A3.1 

$C (alt-modeC) (edita command/parameter) 21.16 

$N (in pattern match compiler) 23.41 

$Q (alt-modeO) (edita command/parameter) 21.13 

$W (alt-modeW) (edita command/parameter) 21.14-15,17 

% (escape character) 2.6; 3.2,10; 14.10-14, 

18-19,25 

% (use in comments) 14.41 

%X (use in comments) 14.41 

6 (in edit pattern) 9.11,21 

& (in pattern match compiler) 23.39 

& (typed by editor) 9.2 

& (typed by system) 14.19 

17.16 

(edita command/parameter) 21.11,14 

(in a lap statement) 18.42 

(in pattern match compiler) 23.39 

(clisp operator) 23.13 

( 3.2; 14.13 

() 3.7 

) 3.2; 14.13 

* (in a lap statement) 18.42 

* (in an assemble statement) 18.39 

* (in pattern match compiler) 23.40 

* (typed by editor) 9.2 

* (in MHD command) (in editor) 9.47 

* (use in comments) 14.30,39 

* (use in prettydef command) 14.36 

*** (in intcrscope output) 20.15 

***** (in compiler error messages) 18.49 

*****A1 rCNlION USER (typed by system) 22.65 

**BREAK** (in backtrace) 15.9 

**COMMrNT** (typed by editor) 9.60 

**COMNENT** (typed by system) 14.31 

**COMMENT**FLG (prettydef variable/parameter) ... 9.61; 14.31 

**CUTOFF** (typed by PRINTSTRUCTURE ) 20.4 

«*E0ITOR«* (in backtrace) 15.9 
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*«TOP** (in backtrace) ..« 15.9 

«ANY« (in edit pattern) . 9.21 

*FORM* 12.4 

, (edita command /parameter ) 21.10 

(in edit pattern) 9.11,22 

-- (in pattern match compiler) 23.41 

(typed by system) 14.20 

-> (break command) 15.11 

-> (in pattern match compiler) 23.46 

-> (typed by dwim) 17.3-4,6-7 

-> (typed by editor) 9.58 

-n (n a number, edit command) 9.3,17 

(-n el ... em) (n a number, edit command) 9.5,36 

3.7; 14.13 

. (edita command/parameter) 21.12 

. (in pattern match compiler) 23.42 

. (in a floating point number) 3.6 

. notation 2.1 

.. (edit command) 9.33 

... (in edit pattern) 9.22-23 

... (prog. asst. command) 22.21-22 

... (typed by dwim) 17.4,6 

... (typed by editor) 9.13,15 

... (typed by system) 14.17; 22.48 

/ (edita command/parameter) 21.9,12 

/ functions 22.40,57-58 

/RPLNODt[X;A;D] 22.57 

(2ND . @) (edit command) 9.30 

(3R0 . 0) (edit command) 9.30 

7 ( instead of • ) 17.16 

8 (instead of left parenthesis) 9.82; 17.2,7,16-18 

9 (instead of right parenthesis) 17.2,7,16-17 

: (edita command/parameter) 21.14 

: (typed by system) 2.8; 15.4 

; (clisp operator) 23.12 

(: el ... em) (edit command) 9.14,40 

; (edita command/parameter) 21.16 

(; . x) (edit command) 9.76 

<»> (use in clisp) 23.16 

= (break command) 15.10 

= (edita command/parameter) 21.13 

= (in a lap statement) 18.41 

= (in pattern match compiler) 23.39 

= (typed by dwim) 17.5,7 

= (type<l by editor) 9.12 

= (in event address) 22.12 

= = (in edit pattern) 9.22 

== (in pattern match compiler) 23.39 

=> (in pattern match compiler) 23.46 

= E (typed by editor) 9.82 

=F.DITF (typed by editor) 9.86 

=EDITP (typed by editor) 9.85 

=EDITV (typed by editor) 9.85 

? (edit command) 9.2,60 

? (edita command/parameter) 21.13 

? (typed by dwim) 17.6-7 

? (typed by editor) 9.3 
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? (typod by system) 16.4 

?= (break command) 15.8-9 

?? (prog. asst. command) 22.21-22 

§ (break command) ' 15.8-9,12 

@ (cditn command/parameter) 21.10 

@ (in ti lap statement) 18.41 

0 (in pattern match compiler) 23.40,42 

0 (in event specification) 22.14,53 

0 (location specification) (in editor) 9.29 

(01 THRU 02) (edit command) 9.54 

(01 THRU) (edit command) 9.56 

(01 TO 02) (edit command) 9.54 

(01 TO) (edit command) 9.56 

00 (in event specification) 22.14,27,53 

[ 3.2; 14.13 

[,] (inserted by prcttyprint) 14.38 

\ (edit command) 9.11,34-35,41 

\ (typed by system) 2.4; 14.10,23 

\ (in event address) 22.13 

(\ atom) (edit command) 9.34 

\P (edit command) 9.11,35.61 

1 2.5; 3.2; 14.13,16 

t (break command) 15.7,16; 16.2,7 

t (edit command) 9.4,18 

t (edita command/parameter) 21.13 

t (use in comments) 14.41 

(edit command) , 9.34 

(in pattern match compiler) 23.43 

(typed by system) 2.4,6; 15.4 

(in event address) 22.12 

^ operator (in clisp) 23.12,15 

(♦- pattern) (edit command) 9.30 

(edit command) 9,34 
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